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Licensing Requirements for Software Oevelopen 

Apple has a low-cost licensing program^ which permits developers of software 
for the Lisa to incorporate Apple-developed libraries and object code files 
into their products. Both in-house and external distribution require a license. 
Before distributing any products that incorporate Apple software, please 
contact Software Licensing at the address below for both licensing and 
technical information. 



©1983 by Apple Corrputer^ Inc. 
20525 Mariani Avenue 
Cupertino, California 95014 
(408) 996-1010 



Apple, Lisa, and the Apple logo are trademarks of Apple Computer, Inc. 
Simultaneously published in the USA and Canada 



CXtstomer Satisfaction 

If you discover physical defects in the manuals distributed with a Lisa product 
or in the media on which a software product is distributed^ Apple will replace 
the documentation or media at no charge to you during the 90-day period 
after you purchased the product 



Pnxlict Revisions 

Unless you have purchased the product update service available through your 
authorized Lisa dealer^ Apple cannot guarantee that you will receive notice of 
a revision to the software described in this manual, even if you have returned 
a registration card received with the product. You should check periodically 
with your authorized Lisa dealer. 



Limitation on Warranties and Liability 

All implied warranties concerning this manual and media, including implied 
warranties of merchaitability and fitness for a particular purpose, are limited 
in duration to ninety (90) days from the date of original retail purchase of this 
product 

Even though Apple has tested the software described in this manual and 
reviewed its contents, neither Apple nor Its software supplien make any 
warranty or representation, either express or implied, with respect to this 
manual or to the software described in this manual, their quality, performance, 
merchantability, or fitness for any particular purpose. As a result, this 
software and manual are sold "as is," and you the purchaser are assuming the 
entire risk as to their quality and performance. 

In no event will Apple or its software suppliers be liable for direct. Indirect, 
special, incidental, or consequential damages resulting from any defect in the 
software or manual, even if they have been advised of the possibility of such 
damages. In particular, they shall have no liability for any programs or data 
stored in or used with Apple products, including the costs of recovering or 
reproducing these programs or data. 

The warranty and remedies set forth above are exclusive and in lieu of all 
others, oral or written, express or implied. No Apple dealer, agent or 
employee is authorized to make any modification, extension or addition to this 
warranty. 

Some states do not allow the exclusion or limitation of implied wananties or 
liability for incidental or consequential damages, so the above limitation or 
exclusion may not apply to you. This warranty gives you specific legal rights, 
and you may also have other rights that vary from state to state. 
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License and Copyright 

This manual and the software (computer programs) described in it are copy- 
righted by Apple or by Apple's software suppliers^ with all rights reserved^ and 
they are covered by the Lisa Software License Agreement signed by each Lisa 
owner. Under the copyright laws and the License Agreement/ this manual or 
the programs may not be copied, in whole or in part, without the written 
consent of Apple^ except in the normal use of the software or to make a 
backup copy. This exception does not allow copies to be made for others, 
whether or not sold, but all of the material purchased (with all backup copies) 
may be sold, given, or loaned to other persons if they agree to be bound by 
the provisions of the License Agreement Copying includes translating into 
arrather language or format. 

You may use the software on any computer owned by you, but extra copies 
cannot be made for this purpose. For some products, a multiuse license may 
be purchased to allow the software to be used on more than one computer 
owned by the purchaser, including a shared-disk system. (Contact your 
authorized Lisa dealer for more information on multiuse licenses.) 
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Preface 



This manual is intended for experienced Pascal^ BASIC^ or COBOL 
programmers. It describes the Workshop system, which is the environment in 
which these languages are used. We assume you have read the Lisa Owner's 
Gujcfe and are familiar with your Lisa system. 

Related Documents 

For Pascal programming: 

• Pascal Reference Manual for the Lisa 

• MC68000 16 Bit Microprocessor User's Manual 

• Cperating System Reference Manual for tne Lisa 
For BASIC programming: 

• BASIC-Plus User's C^cle for the LJsa 
For COBOL programming: 

• CXBOL User's Guide for the Lisa 

' COBOL Reference Manual for the Lisa 

Type and Syntax Conventions 

Boldface type is used In this manual to distinguish program text from English 
text 

Italics are used when technical terms are introduced. 

Syntax diagrams are used to describe file specifiers and the syntax of exec 
files. For example, the following diagram describes a wild-card-spec: 



wlld-caid-spec 

— ^r>" 



String-1 




L^0 . 



String-2 



vil 
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start at the left and follow the arrows through the diagram. Several paths 
are possible. Every path that begins at the left and ends at the arrowhead on 
the right is valid, and represents a valid way to construct a file specifier. 
The boxes traversed by a path through the diagram represent the elements 
that can be used to construct a wild-card-spec. Thus the diagram embodies 
the following rules: 

• A wild-card-spec can begin with a string (string- 1) or the string can be 
omitted. 

• A wild-card-spec must contain one of "-", "7", or "$". 

• The "-", "7', or "$" can be followed by a string (string-2) or the string can 
be omitted. 

The name contained in a rectangular box is the name for some other 
syntactic construction that is specified by another diagram. The name in a 
rectangular box is to be replaced by an actual instance of the construction 
that it represents. 

Symbols such as reserved words, operators, and punctuation, are enclosed in 
circles or ovals. Text in a circle or oval represents itself, and is to be 
written as shown (except that capitalization is not rec^^ired). 
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Chapter 1 
Introduction 



Ll The woiKshop 1-1 

The Workshop provides the functions necessary to develop and run 
programs on the Lisa. The Workshop can be booted from either a 
diskette or a ProFile. 

UZ starting the Workshop 1-2 

The Workshop is started by booting the Lisa from a disk containing the 
Workshop software. You can use the Environments window to select 
one of several availgtole environments. 

1.3 The Woikshop Command Line 1-3 

The Workshop command line gives you access to the main system 
functions and subsystems. All the Workshop commands are described in 
this section, 

L4 File System Organization and Naming 1-6 

Files are stored on disk volumes and are accessed by specifying the 
volume name and the file name. 

13 TTie Woikshop User interface 1-6 

This secticMi gives information on the user interface conventions used in 
the Workshop system. 

1.6 Utility Programs 1-9 

utility programs provide additional functions for the Workshop, A 
utility program is started by choosing the RUN command from the 
Workshop command line. 

1.7 How Do I Install the Pascal Language System? 1-9 

This section provides instructions for installing the Pascal Language 
System onto your ProFile. 

1.8 How Do I Write and Run a Pascal Program? l-ll 

A Pascal program is written with the Editor. The source file must be 
compiled arxj linked before it can be run. 

1.9 How Do I Write and Run an Assembly Language Program? 1-11 

An assembly language program Is written with the Editor, It must be 
assembled and linked with a Pascal main program before it can be run. 
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LIO How Do I Install the BASIC Language System? 1-12 

This section provides instructions for installing the BASIC Language 
System onto your ProFila 

Lll How Do lUse the BASIC Interpreter? 1-13 

A BASIC program can be written using either the Editor or the BASIC 
Interpreter to create the source file. The BASIC Interpreter will run 
the program. 

1.12 How Do I Install the CCBGL Language System? 1-13 

This section provides instructions for installing the COBOL Language 
System onto your ProFile. 

1.13 How Do I Write a CCBGL Program? 1-15 

A COBOL program is written with the Editor. After writing the 
program, enter the COBOL language system to compile and run the 
program. The COBOL system is invoked by pressing c in response to the 
Workshop command pronpt 

1.14 Using the Printer 1-15 

This section provides instructions on how to configure your Lisa for a 
printer. Information is also provided on how to specify a default 
printer when you have more than one printer connected to your Lisa 

L15 The Operating System 1-16 

The Workshop runs under the Operating System for the Lisa computer. 
You can access Operating System routines through the SYSCALL 
interface. More information about this interface can be found in the 
Operating System Reference Manual for the Lisa 
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1.1 The Woikshop 

The Workshop allows you to develop and run programs on the Lisa. It 
provides tools necessary to write^ debug, and run programs in Pascal, BASIC, 
and COBOL. This manual explains how to use the Workshop and all of its 
tools. 

CommEUTd lims provide access to all Workshop functions. The main command 
line, WORKSHOP, allows you to edit programs, run utilities or user programs, 
aid use the languages available on the system. It also provides access to two 
subsystems: the File Manager and the System Msnager. 

The File Manager allows you to copy, delete, rename, arKi list disk files. It 
includes a backup function, aid functions for manipulating volumes. These 
functions are listed in the FILE-MGR command line. (See Chapter 2.) 

The System hiaiager provides for system configuration and defaults gfid 
process managnent Its commands are listed in the SYS-M(^ command line. 
(See Chapter 3.) 

The Lisa system can display one of two screens, called the main screen and 
the alternate screen. The Workshop system normally displays on the main 
screen. The alternate screen is used by the system Debugger. You can 
change to the other screen display by pressing the right hand [OPTION] key and 
holding it down while you press the JENTER] key. The System Manager 
contains the Console command, which caai be used to specify where the 
Workshop should display. 

You can currently use the Workshop to write programs in Pascal, COBOL, and 
BASIC. To use these languages, refer to the appropriate language manuals. In 
addition to this manual, you will need: 

For Pascal Programming: 

• Pascal Refer&Tce Manual for the Lisa 

• t^lC68000 16 Bit Microprocessor User's Manual (if you want to use 
assembly language or the Debugger) 

" Operating System Reference Manual for the Lisa (for information on 
system calls) 

For BASIC Programming: 

• BASIC-Plus User's Guide for the Lisa 
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For CCBOL Programming: 

• CCBOL User's Guide for the Lisa 

• COBOL Reference Manual for the Lisa 

If you have only a BASIC or COBO. system, you will not have all the software 
described in this manual. Specifically, you will not have the Debugger and 
csn disregard the sections that pertain to it The portions of this manual that 
will be most useful to BASIC and CC3B0L programmen are: 

• The Introduction, which describes how to use the Workshop. 

• The File Manager, which describes files and how to mani|xilate them. 

• The System Manager, which describes setting up the system configuration 
parameters, 

• The Editor, which describes how to create and modify text files, which are 
used as source files. 

You may also use some of the utilities if they are included in your software. 

L2 Starting the Workshop 

Tfw Workshc^ can be booted from a diskette or a ProFile*. It will most 
cwnmonly be used with a ProFile^ because hard disks have more space and are 
faster. See the Lisa Owner's Guide for instructions on booting the system. 

To start the system, boot from a disk that contains the Workshop software. If 
your disk contains only the Workshop environment, the Workshop command 
line will appear at the top of the screen. If you have more than one 
environment (for example, the Workshop and the Office System) you can use 
the Environments window to start up the environment you want, and switch 
between environments. 

The Environments window allows >ou to select the environment you want to 
start You can also set a default environment that will be started 
automatically when you boot the system. To access the Environments window 
while booting the system, press any key while the Lisa is starting up. The 
Enviroranents window will be displayed. 

The Environments window is shown in Figure 1-1. It displays five buttons: 

Power Off Turn off the Lisa 

Restart Reboot or reset the Lisa 

Start start the selected environment 

Set Default Set the default to the selected environment 

No Default Display the Environments window on startup. 
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To select an environment, move the pointer to the checkbox of that 
environment and click the mouse button. Then move the pointer to the start 
button and click. The selected environment will start 

To access the Environments window from the Workshop, for example, to select 
another environment, use the Quit command from the Workshop command line. 
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Figure 1-1 
The Environments Window 

13 The Woikshop Command Line 

When you select the Workshop environment, the Workshop command line 
appears at the top of the screen. This command line lists all the primary 
Workshop commands and gives access to several subsystems with additional 
commands. The Workshop line displayed contains only some of the commands 
available. You can see the rest of the commands by pressing "?", the last 
symbol on the line. To return to the original command line, press [RETURN]. 
Pressing the first letter of a command initiates the command. 

Most commands will ask for additional information. Type in the information 
using the Lisa keyboard. Some questions have a default value, displayed in 
square brackets ( [default] \ To accept the default value, press [RETURN]. If 
you don't want the default value, type in the value you want. 

Two other subsystems have separate command lines: the File Manager and the 
System Manager. Their command lines can be accessed from the Workshop 
command line, and are used the same way. 
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The main, or Workshop, command line is as follows: 
WORKSHOP: FILE-MGR^ SYSTEM-MGR, Edit Run, Pascal, Basic, codol. Quit, ? 

The additional portion, displayed by pressing "7', Is: 
Assemble, Debug, Qenerate, MakeBackground Link, TransfarProgram 

All the main command line commaaids are described as follows: 

nLE-MGR(l=) 

This command puts you into the File Manager subsystem, which is used to 
manipulate tr« files and voltffnes on the system. For more information on the 
file manager, see Chapter 2 in this manual. 

SYSTEM-MGR (S) 

This command puts you into the System Manager subsystem. This subsystem 
provides various configuration and utility functions. See Chapter 3 In this 
manual for nrwre information. 

Edlt(E) 

The Edit command puts you into the text editor, which is used to create and 
modify text files. The Editor is used to create source files for BASIC, COBOL, 
and Pascal. It is also used for assembly language programming and to create 
exec files. The Editor is described in Chapter 4 in this manual. 

Run(R) 

The Run command causes a compiled and linked program to execute. This 
command is used for user-written Pascal programs, utility programs, and any 
other software that runs under the workshop. The Run command asks you for 
the file to run. This file must be an executable object file or an exec file. 
When you give the Run command a file name with no .OBJ extension, it will 
first search for that file name. If it is not found, it will search for 
filename.obJ. If you do not specify a volume name, the Run command will 
search through up to three default volumes for the file. (See Section 2.4.1 for 
an explanation of volume name.) These defaults can be set by the File 
Manager's Prefix command. See Chapter 2 for more information on the Prefix 
command. 

The Run command will also accept an "exec file" as input An exec file is a 
scenario of convnarids for the Workshop system to carry out. An exec file 
name must be preceded by a **<" or "exec/" to be processed correctly. For 
more information on exec files, see Chapter 9 in this manuaL 

Pascal (P) 

This command starts the Pascal Compiler. The Compiler asks for the input 
file, which must be a text file; the listing file; and the output file, which will 
contain the object code. The Pascal Compiler is described in Chapter 5. 
Further information on the Pascal language can be found in the Pascal 
Reference Manual for the Lisa. 
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Compilation Is In two steps. The first step, done by the Pascal command, 
produces an intermediate code file. After this, you must use the Generate 
command, (press G) to generate an object file from the Intermediate code file. 

Basic ($) 

This command puts you Into the BASIC Interpreter. More Information on 
BASIC programming can be found In the BASIC-PIus User's Guide for the 
Lisa. 

CGboKO 

This command puts you Into the COBOL language system. More Information 
on COBOL programming can be found in the COBOL User's Guide for the Lisa 
and the COBOL Reference h'ianual for the Lisa 

Quit(Q) 

The Quit command ends the Workshop environment You can use it to access 
the Environments window to start another environment or to turn off your 
Lisa 

The following prompt line appears after you confirm that you want to leave 
the shell: 

WorkShop_shell, Another_shell, Reboot, Power_off 

Type the first letter of what you want to do, for exannple, type A to access 
the Environments window. 

Assemble (A) 

The Assemble command starts the assembler. Further information on the 
assembler can be found In this manual in Chapter 6. Additional information on 
the assembly language can be found in the MC68000 16 Bit Microprocessor 
User's Manual 

Debug (p) 

The Debug command causes your program to run with a breakpoint Inserted at 
the first Instruction in the program, so you can use the debugger on the 
program. More Information on the Debugger can be found In Chapter 8 of 
this manual. 

Generate (G) 

Tl^ Generate command converts intermediate code files produced by the 
Pascal compiler into object code. It is used with the Pascal Compiler and is 
described in Chapter 5. 

MakeBackground (M) 

The MakeBackground command allows you to start up a background process, 
then continue usir^ the Workshop for other functions. It is assumed that the 
background process will not try to display on the console or require keyboard 
input. 
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Link (L) 

TTie Link connmaBTd executes the Linker. The Linker is used to prepare 
compiled Pascal programs and assembled routines for execution, aid to link 
together separately compiled pieces of a program. The Linker is described in 
Oiapter 7. 

TransfeiProgram (T) 

The Traisfer Program allows your Lisa to communicate with a remote 
corrputer. It can be used as a terminal, or to transfer files between the Lisa 
arc! the rerrote computer. The Transfer Program is described in Chapter 10. 

L4 File System Organization and Naming 

Files are stored on volumes, that are mounted an devices. A volume has a 
name and a directory of files that it contains. A file is specified by giving 
the name of the volume and the name of the file: 

-volunename-filename 

The Workshop maintains a working directory; you can access files in it 
without specifying a volunne name. The working directory can be changed by 
using the File Manser's Prefix command. Files on the working directory can 
be specified by just the file name, with no leading "-": 

filename 

Further informatioi on the file system can be fourxj in Chapter 2 of Uiis 
manual and in the Operating System Reference Manuai for the Lisa. 

IS The Workshop User Interface 

This section describes conventions and standards used in the Workshop system. 
These ways of requesting irput from the user are standard throu^iout the 
system to msrice it easier to use. 

L5.1 File Name Prompts 

Many of the Workshop pronpts are for file names. In the Lisa Operating 
System, you have few restrictions on what characters you can put in file 
names. However, you should be aware that the following restrictions exist in 
the Workshqf): 

1. You can entjed blanks, but leading ard trailing blanks and tabs will be 
removed when the Workshop processes your file pronpt infMJt. 

2. Cases are preserved as you specify them. 

A pathname has three parts: a device name, a file name, and an extensioa 
The following conventions apply to a path name: 

device (or volume) name is up to 32 characten long, excluding •-'. 

file nane is composed of alphabetic or numeric 

characters; spaces are permitted. 
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extension is corrposed of alphabetic or numeric 

characters; spaces are permitted. N\ 
extension is optional. If present, it is the 
final *.' and any characters that follow 
(there must be at least one) in the 
pathname. 

The combined length of the file name, plus extension, cannot exceed 32 
characters. 

Prompts often include default values. You do not have to enter parts of file 
nanes already supplied by defaults. 

If a prompt includes a default extension which you don't want (except if the 
file name consists of only a logical device name), put a period at the end of 
the file nane. The period will be removed and no extension will be added. 

The following sections explain the standard responses allowed to prompts. 

IS.1.1 The CLEAR Key 

The [CLEAR] key on the Lisa keytraard is an escape key. You can use it in 
response to a file name prompt to abort out of the command or program. No 
[RETURN] is required after pressing the key. 

L5.L2 Prompts with single Default values 

When a default value for part of a file name exists, it is shown enclosed in 
brackets in the prompt message; for example, [.text] Indicates that there is a 
default file name extension value, and that that value is .text If a default 
value is present, you need specify only the file name part not supplied by the 
default 

Extensions will rrat be added to file specifications consisting of device names 
only. Therefore, if you want to specify only a device when there is an 
extension default (for example, when prompted for a listing file with a default 
extension .TEXT and you want -printer), simply use -printer. 

To use the default value for an entire file name, respond with [RETURN]. If 
you do not want any file to be used, even if a default value exists, respond 
with a backslash "\". 

L5.1.3 Prompts with Alternate Default values 

Alternate defaults are Indicated by a slash. For example: 

[-console]/[.text] 

means you have a choice of either the console or a ".text" file. To choose the 
console, simply press [RETURN]. To choose a text file, respond with a file 
name. 

L5.1.4 Prompts with Separate Default values 

Each of the parts of a file name might have a separate default value, such as 
[-paraport] [-intrinsic] [.lib]. If each of the defaults is Independent 
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• a response with no device specification gives you the default device. 

• a response with no file name gives you the default file name. 

• a response with no extension gives you the default extension. 

Sometimes the defaults depend upon each other. For instance, the prompt 
[-paraport-intrinsic] [.lib] indicates dependency, because the first two 
components are enclosed in the same set of brackets. When defaults are 
dependent, if you choose one or the other of them, you will get both. Be sure 
to look at what has been included in the brackets to see whether the defaults 
are independent or not 

13.13 Prompts with No [Default Values 

If you find that no default value is given in the file name prompt, use 
[RETURN] or a backslash to specify no file. Sometimes a file is required for 
the system to perform its function. If this is the case, and you specify no 
file, the program terminates. 

13.1.6 Encting a List of Prompts 

Some Workshop tools prompt for lists of files, as does the Linker. To indicate 
that you are finished responding to a prompt for a list of files, use [RETURN]^ 

L5.L7 The ? Response 

If you need help, or a list of program options, respond to a file name prompt 
by pressing the ? key followed by [RETURN]. Then proceed according to the 
information that appears on your screen. 

13^ How to Terminate an Operation 

You can terminate the operation of most commands and programs by pressing 
•-period, although termination might not be immediate if the program being 
run does not recognize «-period. 

NOTE 

Note that most Workshop tools check for «-period from the keyboard 
even when running under exec files. This means that you can abort 
Workshop tools in exec files. 

Unless user programs are written to recognize the «-period key combination 
as an abort mechanism, pressing those keys will not terminate the program 
being run. (See PASLIBCALL, Section 5.4, for information on the function 
PAbortFlag, which tells whether or not those keys have been pressed.) If this 
is the case, you can either: 

• wait for the user program to terminate so that «-period can be recognized 
by something else, or 

• press the NMI key, which forces the system into the Debugger. The NMI 
key is the "-" key on the numeric keyboard. 

See Section 8.2 for instructions on how to stop a user program early. 
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1S3 How to Halt a Screen Display 

If you want to temporarily stop the screen display^ press the # key and type 
S^ which stops the program from running by blocking its current output 
operation. When you want to restart the screen display, again press *-S. 

1.5ja Inserting and Ejecting Diskettes 

You can usually insert a diskette at any time. It will be mounted and 
accessible after you press any key, except the C [CAPS LCCK], [CPTION], or 
[SHIFT] key, on the keyboard. You can usually eject a diskette by pressing 
the diskette button and then hitting any key on the keyboard. (When you are 
in the Editor, the Preferences tool, or TransferProgram, you do not need to hit 
a key after pressing the diskette buttoa) 

Mounting and unmounting diskettes is handled by the Pascal run-time system 
in the Workshop. Therefore, the act of inserting a diskette or pressing the 
eject button is not recognized until Pascal I/O is performed, thus the necessity 
of hitting a key. If the program you are running does not use Pascal I/O, you 
must first return to the Workshop command line. Then enter the File Manager 
and Mount or Unmount your diskette. 

1.6 Utility Programs 

The Workshop provides various utility programs, which support functions used 
less often than the functions you obtain through primary commands. The 
utilities are described in Chapter 10. 

You must Run utilities. Choose the Run command from the main command 
line by pressing R when the main command line is displayed. The system will 
ask you for the name of the file to run. Type in the name of the utility you 
want to run. 

1.7 How Do I Install the Pascal Language System? 

Because the Lisa Office System is a standard product, you must install it 
before you install any optional language systems. 

To Install the Pascal language system, start with your ProFlle on and your 
Lisa off. 

1. insert the "Pascal 1" Lgffiguage System diskette Into your Lisa's i^pper or 
lower disk drive. 

2. Press the on-off button. 

3. Hold down the <l key and type either l. If you put the diskette in drive 1 
(the upper drive), or 2, if you used drive 2 (the lower drive). 

0. Walt It win take about 3 minutes for the Lisa to load in the Operating 
System and the Workshop shell from the diskette. 
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NOTTE 

If you want to stop the loading process at any time after the system 
has booted, hold down the « key while you type a period. The system 
will stop copying files and you will enter the Workshop environment. 

5. When the system is finished booting, you will see some information about 
the clstarttext exec file and about initializing ProFiles. Then the system 
will ask you a series of questions. Be sure to type [RETURN] to terminate 
your responses. 

• The system will ask if you want to go ahead with the process. (Type Y 
for yes.) 

• The system will ask you where the target ProFile is attached. It must 
be attached to the built-in parallel connector (PARAPORT), or the 
upper or lower connector of the parallel Interface card in expansion 
slot 2 (SL0T2CHAN2 and SL0T2CHAN1, respecUvely). 

• The system will then ask you to insert the second Workshop diskette, 
"Pascal 2". 

• The system will then ask if your ProFile needs to be initialized. Do 
not initialize your ProFile if there is already an Office System on it! 

• If you don't initialize your ProFile, the system will ask you if you have 
enough space on the target ProFile. "Enough space" for a whole 
Workshop means about 1500 blocks. If you already have another 
Workshop Language System on the ProFile, then "enough space" means 
about 700 blocks. (The language systems share about 800 blocks.) 

• If you do initialize your ProFile, you will be asked if there is now a 
Lisa OS volume on it. Answer Y if the ProFile has ever been used with 
a Lisa. 

You will now see a lot of text flash by on your screen—don't worry, this is 
supposed to happen. The commands you generated by answering the questions 
are now actually being executed. 

If you get any error messages, stop the process by typing «-perlod, turn off 
your Lisa, and start over. If you get the same error again, write it down, and 

call the Apple® Support Hotline to find out what to do. 

When all the files on the "Pascal 2" diskette have been copied, the system 
will eject the diskette and ask you to insert the "Pascal 3" diskette, then 
continue to copy files. 
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When the system is finished copying files, the Workshop command line will 
appear. 

L8 How Do I Write and Run a Pascal Program? 

To write and nm a Pascal program, proceed as follows: 

1. Use the Editor to create a text file with the Pascal source program. See 
Chapter 4 in this manual for more information on editing the file. See the 
Pascai Reference Manuai fiar the Lisa for information on the language. 

2. Compile the progran with the Pascal command (press P while the 
Workshop command line is displayed). The output from the compiler is an 
intermediate file. 

3. The output from the Pascal command is an I-code file. Use the Generate 
command to convert the I-code file into an object file. To use the 
Generator, press G when the Workshop command line is displayed. See 
Chapter 5 for more information on compiling Pascal programs. 

U. Lirt< the program with the Link command, in order to be executable, the 
program must be lirtced with the Pascal support routines contained in 
IOSPASLIB.CBJ. If you are using any REAL variables, you must link your 
program to IOSFPLIB.CBJ. For other spDlications you can also use other 
libraries and units, or assembly language routines. More information on 
the Linker can be fotnd in Chapter 7. 

5. The linker produces an executable object file. Press R to run the program. 

Information on making system calls from Pascal can be found in the Cperating 
System Refisrence Manuai fior tiie Lisa. 

1.9 How Do I Write and Run an Assembly Language ProgiBm? 

Assembly language programs must be called as procedures or functions from a 
Pascal main program. To write an assembly language routine, proceed as 
follows: 

1. Use tfre Editor to create an assembly langua^ source program. See 
Chapter 6 of this manual for information on assembly language. Chapter a 
describes the Editor. 

2. Press A to execute the Assembler. The Assembler accepts the text file 
you created and produces an object file. 

3. Declare the routines ycHJ wrote in assembly language as EXTERNAL in the 
main Pascal program that calls them. 

4. Use the Pascal and Generate commands to create an rtDject file fran the 
Pascal program. See Section 1.8 for more information. 
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5. Use the Link command to link the Pascal object file^ the assembly object 
file, IOSPASLIB.0BJ, and any other needed units or libraries. 

6. Use tt^ Run command to run U« resulting object file. 

LIO How Do I Install the BASIC Language System? 

Because the Lisa Office System is a standard product, you must install it 
before you install any optional ISBiguage systems. 

To install the BASIC language system, start with your ProFile on and your 
Lisa off. 

1. Insert the "BASIC 1" Language System diskette into your Lisa's upper or 
lower disk drive. 

2. Press the on-off button. 

3. Hold down the # key and type either 1, if you put the diskette in drive 1 
(the upper drive), or 2, if you used drive 2 (the lower drive). 

4. Wait It will take about 3 minutes for the Lisa to load in the Operating 
System and the Workshop shell from the diskette. 

NDfTE 

If you want to stop the loading process at any time after the system 
has booted, lx>ld down the « key while you type a period. The system 
will stop copying files »id you will enter the Workshop environment 

5. When the system is finished booting, you will see some information about 
the cistarttext exec file and about initializing ProFiles. Then the system 
will ask you a series of questions. Be sure to type [RETURN] to terminate 
your responses. 

• 1\^ system will ask if you want to go ^lead with the process. (Type Y 
for Yes.) 

• The system will then ask you where the target ProFile is attached. It 
must be attached to the built-in parallel connector (PARAPORT), or the 
upper or lower connector of the parallel interface card in expansion 
slot 2 (SL0T2CHAN2 and SL0T2CHAN1, respectively). 

• The system will then ask you to insert the secorxl Workstx^ diskette, 
"BASIC 2". 

• The system will then ask if your ProFile needs to be initialized. Do 
not initialize your ProFile if there is already an Office System on it! 
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• If you don't initialize your ProFile, the system will ask you if you have 
enough space on the target ProFile. "Enough space" for a whole 
Workshop means about 1500 blocks. If you already have another 
Workshop Language System on the ProFile, then "enough space" means 
about 700 blocks. (The language systems share about 800 blocks.) 

• If you do initialize your ProFile, you will be asked if there is rww a 
Lisa OS volume on it Answer Y if the ProFile has ever been used with 
a Lisa. 

You will now see a lot of text flash by on your screen—don't worry, this is 
supposed to happen. The commands you generated by answering the questicns 
are now actually being executed. 

If you get any error messages, stop the process by typing «-period, turn off 
your Lisa, and start over. If you get the same error again, write it down, and 
call the Apple Support Hotline to find out what to do. 

When all the files have been copied, the Workshop command line will appear. 

1.11 How Do I use the BASIC Inteipieter? 

To use the BASIC Interpreter, proceed as follows: 

1. Use the Basic corrvnand by pressing B when the main command line is 
displayed. You will enter the BASIC Interpreter. 

2. Enter the BASIC language statements and commands necesary to write and 
execute your program. The BASIC Interpreter can execute statements 
immediately or save them to run later. You can return to the main 
commaid lire by using the BASIC commgBid BYE. 

You may also use the Editor to prepare or modify the BASIC source program, 
then use the BASIC Interpreter to run it See Chapter ft in this manual for 
more information on the Editor. 

See the BASIC-Plus User's Guide for the Lisa for more information on the 
language. 

1.12 How Do I InstaU the CGBGL Language System? 

Because the Lisa Office System is a standard product, you rrnjst install it 
before you install any optional language systems. 

To install the CCBOL language system, start with your ProFile oi »id your 
Lisa off. 

1. Insert the "COBOL 1" Language System diskette into your Lisa's upper or 
lower disk drive. 

2. Press the wi-off button. 

3. Hold down the * key and type either 1, if vou put the diskette in drive l 
(the u|:^r drive), or 2, if you used drive 2 (the lower drive). 
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4. Wait It will t€y<e about 3 minutes for the Lisa to load in tiie Operating 
System and the Workshop shell from the diskette. 

, NOTE 

If you want to stop the loading process at any time after the system 
has booted, hold down the # key while you type a period. The system 
will stop copying files, display "Exec processing aborted", and you will 
enter the Workshop enviromient. 

5. When the system is finished booting, you will see some information about 
the cistarttext exec file and about initializing ProFiles, Then the system 
will ask you a series of questions. Be sure to type [RETURN] to terminate 
your responses. 

• The system will ask if you want to go ahead with the process. (Type Y 
for Yes.) 

• Tl^ system will ask you where the target ProFile is attached. It must 
be attached to the built-in parallel connector (PARAPORT), or the 
upper or lower comector of the parallel interface card in expansion 
slot 2 (SL0T2CHAN2 and SL0T2CHAN1, respectively^ 

• The system will then ask you to insert the second Workshop diskette, 

"COBOL 1". 

• The system will then ask if your ProFile needs to be initialized. Do 
not initialize your ProFile if there is alreajy an Office System on it! 

• If you don't initialize your ProFile, the system will ask you if you have 
enough space on the target ProFile. "Enough space" for a whole 
Workshop means about 1500 blocks. If you already have another 
WorkshoJD Language System on the ProFile, then "enough space" means 
about 700 blocks. (The language systems share ^out 800 blocks.) 

• If you do initialize your ProFile, you will be asked if there is now a 
Lisa OS volune on it Answer Y if the ProFile has ever been used with 
a Lisa. 

You will now see a lot of text flash by on your screen—don't worry, this is 
supposed to happen. The commands you generated by answering the questions 
are now actually being executed. 

If you get any error messages, stop the process by typing «-period, turn off 
your Lisa, end start over. If you get ttre same error again, write it down, ^id 
call the Apple Stqaport Hotline to find out what to do. 

W^«n all the files have been cqDied, tt^ Workshop command line will appear. 
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L13 How Do I Write a CGBGL Program? 

To write a COBOL program, proceed as follows: 

1. Create a text file containing the source progr^n by using the Editor. See 
Chapter 4 in this maaiual for more information on the Editor. 

2. Press C to enter the COBOL language system. More information on COBOL 
programming can be found in the CCBOL User's Guide for the Lisa and the 
COBOL Refierence Manual for the Lisa 

Use the Quit coomand to exit back to the main command line. 

L14 Using the Printer 

To use a printer with the Workshop system, you must set up the printer 
correctly, and configure your system for the printer. If you have more tha^ 
one printer you will want to set up one of them as the default printer. These 
(^rations are explained below. 

Setting ip the Printer 

The procedure for setting up a printer varies with the type of printer. See 
the instruction manual that came with your printer for directions on how to 
set it up correctly. 

If your printer is an Apple Imagewriter, the default standards which have been 
factory preset should be satisfactory for normal use. However, if you want to 
modify the performance of the Imagewriter, you can get the technical 
specifications from the Afpie imagewriter User's hianual. Part I: Reference. 

Configure Your Lisa for a Printer 

Follow these steps to configure your Lisa for a printen 

1. From the Workshop command line, press S to enter the System Manager 
subsystem. 

2. Then press P for Preferences. The Preferences tool is used to set 143 the 
configuration of tt^ Lisa system and the Workshop. 

3. Click on Device Connections to display what devices are connected to the 
Lisa. 

tt. Select the port to which ycxjr printer is collected. When you select the 
port, all devices that can be connected to that port are displayed. 

5. Select printer, and additional configuration options are displayed. 

6. When yoj are finished configuring your printer, select Quit from the Tools 
menu. 

7. Then exit from the System Manager back to the Workshop command line 
by pressing Q for Quit 



1-15 



Workshop User's Guide IntroctucUon 



Any changes made with the Preferences tool are made immediately to 
Parameter Memory, but changes in device connections do not take effect until 
the next time the Lisa is booted. Therefore, if you want to continue working, 
it is necessary to reboot your Lisa now. For additional information on the 
Preferences Tool, refer to Section 3.3. 

To reboot, perform the following steps: 

1. Press Q for Quit 

2. Select Y in answer to "Are you SURE you want to LEAVE the shell?" 

3. Press R for Reboot. 

When the system has finistwd rebooting, the charts you made will be in 
effect. 

Setting a Default with Multiple Printers 

If you have multiple printers connected to your Lisa, you can specify which 
one is to be tr« default printer. This means that you can eststolish which 
printer will be designated by -printer. 

First configure all of the devices you want connected to the Lisa (See the 
previous section and Section 3.3 for instructions on configuring devices.) 
After you have rebooted, return to the System Manager command line. Select 
D for DefaultPrinter, and enter the device name of the default printer. If you 
do not want to chaige the device name, becajse you want the default to 
remain as it is, press [RETLRN] to exit back to the System Manager cornmesTd 
line. 

Rebooting is not required for the default printer setting to take effect 
However, if output redirect to the printer is in effect, you will have to do the 
output redirection again. 

Details on the DefaultPrinter option are available in Section 3.2. 

1.15 The Gpeiating System. 

The Workshop runs under the Operating System of the Lisa computer. You can 
use some Operating System routines from a Pascal program to perform special 
system functions for you. These system calls are defined in the intrinsic unit 
SYSCALL. The dependencies of the Lisa workshop environment are shown in 
Figure 1-2 on the following page. 

More information on the SYSCALL interface and routines can be found in the 
Lisa Operating System documentation. 
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Chapter 2 
The File Manager 



Zl The File Manager 2-1 

The File Manager allows you to manipulate files^ volumes, and devices. 

23. Using the File Manager 2-1 

Press F at the Workshop command line to display the File MsB-^ger 
commands. The first letter of each File Manager command invokes 
that command. 

23 The File Manager Commands 2-1 

This section lists and defines all File Manager operations. 

2.4 The Workshop View of Files 2-8 

Each disk can contain a volume which has a directory of files. File 
extensions (.TEXT, -OBJ, and so forth) are added to some files with 
special uses. 

2.5 Using Wild Card Characters 2-11 

Wild card characters allow you to name groups of files by giving 
filename patterns to be matched. The wild card characters are -, $, ?. 

2.6 How Do I List Existing Files? 2-15 

To list all the files on a volume, use the List command or the Names 
command. You can use wild cards to list subsets of the files on the 
volume. 

Z7 HOW Do I Copy a File? 2-13 

To copy a file, use the File Manager Copy command. Similar to the 
Copy command, the Backup command is also used to copy files. If you 
want the old file deleted after the copy operation is successful^ use the 
Transfer command. You can copy multiple files by using wild cards. 

Z8 HOW DO I Delete a FUe? 2-14 

To delete a file, use the File Manager Delete command. You can 
delete more than one file by using wild cards. 

2.9 How Do I Create and Use a Volume? 2-15 

Use the Initialize command to create a volume. The volume must be 
mounted before you can use it. 
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2.10 How Do I Change the Name of a File or Volume? 2-15 

To Change the name of a file or volume, use the Rename command. 



The File Manager 



2.1 The FUe Manager 

The File Manager is a subsystem of the Workshop. It provides file and device 
manipulation facilities^ and handles most of the tasks of transferring 
information from one place to another. Using the File Manager, you can do 
such things as make copies of files, list directories, rename or delete files, 
find out what volumes are on line^ initialize new disks or diskettes, print files, 
and so oa See the CpeiaUng System Reference Manual for the Lisa for more 
information on the File System and supported devices. 

Z2 Using the FUe Manager 

To use the File Manager, press F in response to the Workshop command 
prompt The File Manager begins executing, and displays the File Manager 
prompt line: 

FILE-MQR: Backup, Oapy„ Delete, List, Prefi)^ Rename, Transfer, Quit, ? 

Pressing "?" displays the additional command line: 

Equal, FileAttiltiutes, Initialize, Mount, Names, Online, Scavenge, Uhmount 

To redisplay the original command line, press [PETURN]. 

To execute any command, press the fint character of that command name 
while the File Manager command line is displayed. Most commands ask for 
file names, or other input parameters. If there is a default value for a 
parameter, it is displayed in square brackets ( [default] \ To accept the 
default, jLRt press [RETURN). If you do not want the default, type in the 
value you want 

To manipulate files with the File Manager you need to address the file with a 
file specifier. A file specifier cai be an OS pathname (representing a file on 
a disk or diskette), an OS volume name (for example, -MYDISK), the name of a 
physical device (for example -RS232A), or the name of a logical device (for 
example -printer). File specifiers can contain wildcards enabling them to 
specify a collection of files. See Section 2,5 for more information on 
wildcards. See Section 2A for more information on file specifiers. 

23 The File Manager Oommends 

The File Manager commands are listed in the File Manager prompt line. They 
are: Backup, Copy, Delete, List, Prefix, Rename, Transfer, Quit, Equal, 
RleAttributes, initialize. Mount, Names, Online, Scavenge, and Uhmount 

Each of these operations is described below. Information on wild card 
characten can be found in Section 2.5. 
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23.1 Backup (B) 

The Backup command executes a simple backup utility, similar to Copy. It 
asks for source and destination file specifien, which will most likely contain 
wild cards (see Section 25\ It then compares the source files to the 
destination files. Whenever the contents of the two files are not equal, the 
source file is copied. If a source file is missing from the destination, it is 
copied. Thus it copies only different files from the source to the destination. 

NOTE 

The destination file is temporarily named Workshop.temp, and the 
source file is automatically cqsied. If the copy is successful, the 
destination file is renamed with its original name, and the files are 
compared. If the files are different, the first file is deleted. Ordering 
the process this way prevents deletion of the destination file before 
verification that the source file is good. 

Because the file name Workshop.temp is internally involved in the 
Backup command, do not assign that name to your files. 

23.2 Copy(C) 

The CoJDy command copies files. It asks for a source file specifier and a 
destination file specifier. You can use wild cards if you want to copy more 
than one file. The source file(s) are not changed by this corrvnand. 

The default is not to verify copy operations. You can change this default 
with the Validate command in the System Manager. If you change the 
default, the source file is compared to the destination file after the copy 
operation to ensure that they are the same. The Validate command is 
described in Ch^ter 3. 

Text files are handled specially when copied to the -printer or -console 
logical devices. Leading blanks in a line of text might have been replaced by 
a (JDLE/xxjnt) pair to save disk space. As such patterns are detected, they are 
replaced by (count) blanks in the copy of the file sent to the printer or 
console. All other files are sent byte by byte unchanged. 

233 Delete (D) 

The Delete command is used to delete a file or a number of files specified by 
a wild card expressioa It asks you to specify U« files to be cteleted. 

23A List(L) 

The List command lists information about the files matching the given file 
specificatioa If all you need is the names of the files, use the Names 
command described in Section 2.3.13. 
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• If the file specifier is a file name (for example -MYDISK-example.text) 
information from only that file is listed. 

• If the file specifier is a volume name (for example -MYDISK), information 
about all files on the volume is listed. 

• If the file specifier includes a wildcard character (for example, 
-MYDISK— .text) information about all matching files is listed. 

The list corrvnaBxl displays the following information: 

Filename The name of the file. 



Size 

Psize 

Lajt-ModHDate 

Creation-Date 

Attr 



The logical file length in bytes. 

The physical file length in blocks (512 bytes). 

Date ^xj time the file was last ch^iged. 

Date and time the file was created. 

File attributes, a combination of the following: 



C 

L 



File was closed by the Operating System. 

File is locked. It cannot be deleted until the file 

safety switch is turned off. (See FileAttributes 

command later in this sectioa) 

File was left open when the system crashed. 

File is protected. 

File has been scavenged. 



An example of the list display is shown in Figure 2-1. 



Contents o^ volume 
Filenane 



-paraport-= 

Size Psize 



SYSTEM. 0EBU62 

SYSTEM. I UDl RECTORY 

SYSTEM.LLD 

SYSTEM.LOG 

SYSTEM. 08 

SYSTEM.SHELL 

XEJECTEM.OBJ 



Last-Mod-Date Creation-Date Attr 



7148 

nu 
mi 

188928 

8704 

512 



H848 29 03/03/83-15!4< 04/10/82-21:57 



14 
18 
6 

17 

1 



07/18/83-09:31 
04/02/82-00:24 
07/18/83-14:54 
05/04/83-10:08 
04/02/82-00:24 
04/02/82-00:27 



02/23/83-10:33 
02/23/83-10:24 
04/08/83-17:49 
05/04/83-10:08 
03/29/83-15:14 
03/29/83-15:22 



Figure 2-1 
TTie List Display 

233 Prefix (P) 

The Prefix command enables you to set 143 ctefault volume names to search 
when you specify a file rsime without a volume name. You can set up to three 
volume names that will be searched in order., wr«n you try to rm a program, 
until the file is found. The first prefix is the name of the working directory. 
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It will be searched anytime you specify a file name without a volume name. 
The second arxl third prefixes are searched when you try to Run a program 
without specifying the volume it Is on. 

. NOTE 

The second and third prefixes affect the running of progratfns directly 
from the Workshop shell. They are not searched for programmatic file 
operations^ such as opening files, or for other File Manager operations. 

The last option of the Prefix command asks if you want to initialize the 
Prefix set at boot time. Answer Y if you wait what you have entered to be 
established as defajlts when you boot. 

This commaid asks you for the three prefixes. If you want to accept the 
default. If any, press [RETURN], if you want to set a prefix, type In the 
volume name that you want If you want to have no prefix, press [CLEAR] as 
the prefix for that level. 

23.6 Rename (R) 

The Rename command enedDles you to change the nane of a file. It asks for 
the file name to change and the name to change it to. You can also use the 
Rename corrvnand to chancy tf« name of a volume. The Rename ccMTvnand 
can change the name of a number of files specified by wild cards. See 
Sections 2.5 and 2.10 for more information on using wild cards and renaming 
files. 

2.3.7 TransfferfT) 

The Transfer command asks for an Input file specifier and a destination file 
specifier. It copies the input file(s) to the destination and then, if the copy 
was successful, deletes the Input flle(s). However, if you Transfer to the 
-console or the -printer, the input flle(s) will not be deleted. 

23^ Quit(Q) 

The Quit command exits from the File Manager subsystem beCk to the 
Worksfx^ commaid line. 

23.9 EC|lJal(E) 

The Ec^ial corrannand corrpares the contents of two files to determine if they 
are exactly the same. It asks for the names of the files to compare, then 
compares them byte by byte and tells you if they are equal or unequal. 

Z3.10 FileAttiibutes (F) 

This command is used to set and clear file attributes. You can set the safety 
attribute, which prevents you from accidentally deleting a file. Ytxj can also 
make a file into a protected master (see below). 

To use the FileAttributes command press F in response to the File Manager 
command prompt It displays the command line: 

FlleAttiibutes: ClearAttributes, Safety, Protect, Quit 
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These commands are accessed by pressing tne first character of the commana 
They perform the following functions: 

Clear Attributes (C) 

The ClearAttributes command clears the c, 0^ and S attributes on the 
specified volume, file, or set of files with wildcards. These attributes are set 
by the system, and have the following meanings: 

C File was closed by the Operating System. 
File was left open when the system crashed. 
S File has been scavenged. 

See the Scavenge command in Section 2.3.15 for more informatloa 

Safety (S) 

The Safety command allows you to set or remove the safety attribute (L) on 
any file. When the safety attribute is set, the file is called "Locked" and 
cannot be deleted To delete a file with safety on, use the Safety command 
to remove the attribute, then delete the file. 

Protect (P) 

The Protect command Is used to make an executable object file Into a 
protected master. This is a form of copy protection for programs. Once a 
file Is made Into a protected master, this protection cannot be removed. A 
protected master has the following characteristics: 

• It can be run on any Lisa machine 

• It can be copied on any Lisa machine. 

• Copies made will run only on the Lisa that made the first copy of the 
file. 

NOTE 

Once a file is made Into a protected master, there Is no way to 
unprotect It Be sure you undentand the characteristics of a protected 
master before you create one. 

This protection scheme Is for executable object files. Note that 
protecting a file does not prevent you from deleting It. 

Qult(Q) 

The Quit command exits from the FlleAttrlbutes subsystem to the File 
Manager. 

23.11 IniUalizeOO 

The Initialize command Is used to format and Initialize the File System on a 
diskette or ProFile. It asks you for the device name to Initialize, the number 
of blocks to Initialize, and the volume name. If you want the entire device to 
be Initialized, press [RETURN] for the number of blocks (accepting the 
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defaultX If the device is a diskette, it is formatted (PrcFiles are factory 
formatted). Boot tracks are automatically written to any device that is 
initialized. An initialized device is automatically mounted. 

The initialize command warns you If you attempt to Initialize a disk that 
already contains a volume^ because the contents will be erased. A volume Is 
Initialized to allow a certain maximum number of files. You can make this 
number larger or smaller (If you know you will have a large number of small 
files, for example) when Initializing It 

Z3.12 Mount (M) 

The Mount command Is used to make an OS device accessible. It requests a 
device name. It should be used whenever you connect a new device, such as a 
ProFlle. The Unmount command, described In Section 2.3.16, is used to 
remove a device. All configured devices are mounted at boot time. The 
configuration can be changed with the Preferences tool, which Is described In 
Section 3.3. 

23.13 Names (N) 

The Names commarol is a faster version of the List commaid. It gives you a 
list of file names only. It asks for a file specifier, and displays the names of 
all files matching the given file specifier. 

2.3.14 online (C9 

The Online command produces a list of all the devices that are currently 
mounted and available, with the following Informatloa- 

DeviceName The name of the device. 
VdlumeName The name of the volume. 
VdlSize The number of blocks on the volume. 

FreeBIks The number of blocks still available. 

Files The number of files stored on the volume. 

Open The number of files open on the volume. 

Attr The attributes of the volume: 

B The Boot volume. 

P The Prefix volume (Prefix l). 

M volume Is currently mounted. 

The Online display Is shown In Figure 2-2. 
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23.15 Scavenge (S) 

The Scavenge comrnand runs the OS Scavenger^ which restores damaged files. 
Flies can be damaged any time the Operating System terminates aonormally. 
The Scavenger searches through a disk and restores its directories^ files^ and 
allocation tables to a consistent state. 

To scavenge a disk, use the Scavenge command and specify the device name. 
After the scavenge is complete, use the Mount command to mount it again, 
and continue using it The boot volume cannot be unmounted; therefore it 
cannot be scavenged. If the ProFile is normally your boot volume and you 
need to scavenge it, it Is necessary to boot from a diskette or another ProFlle 
and run the Scavenger from It 

If a file Is changed in any way by the Scavenger, the file attributes are set to 
S, for scavenged. This attribute Is displayed by the List command. The 
changes made to the file might or might not affect the data in the file, 
depending on what state the file was in when it was scavenged. Examine any 
file that has the scavenged attribute before relying on its contents. After the 
file has been checked, you can remove the scavenged attribute with the 
FileAttribute command. 
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^___ NOTC 

A di^'s File System caffi get into an inconsistent state if the Operating 
System terminates abnormally, because the directories and allocation 
tables are kept in memory and only written out to disk periodically. If 
there is an abmrmal termination, such as a power failure, the changes 
to the state of the File System since these tables were written to disk 
might be lost Information can also be lost if you disconnect a ProFile 
from the Lisa without first unmounting it If the disk is used after 
such an event, more data can be lost if the system allocates the same 
blocks to more thsn one file. 

The Scavenger always returns the disk to a consistent state, but it is 
possible to lose data when the system crashes. This damage can 
become even worse if the disk is used while in an inconsistent state. 

All scavenged files should be checked before you depend on their 
contents. 

23.16 Unmount (U) 

This command makes a device inaccessible (takes it off UneX It asks for a 
device name. For diskettes, use a volume name to unmounC or a device name 
to unmount and eject, the diskette. Always unmount a device before 
disconnecting it from a running machine. 

Z4 The workshop View of Files 

Workshop users are provided with a view of files and devices that Is actually 
a composite of what is provided by the Lisa Operating System, the Pascal 
run-time system, and the File Manager itself. Each contributes a specific set 
of facilities; 

• The Lisa Operating System provides support for a variety of input and output 
devices, including txi\h ijJock-stnx^tumcf cte{/ices{(^\'^% and diskettes) and 
jsa^Msw/y^ ^jfj^toRj" (RS232 ports, consoies)L 

• The Pascal run- time system provides support for several loglcal-cfei^ces 
(console, printer, keyboard) which are not provided by the OS. 

• The File Manager provides wild-card facilities which enable many File 
Manager commands to be applied to a whole set of files, rather than just 
one at a time. 

2A1 08 Volumes on Disk 

Every block-structured device is organized as a single volume with a flat 
directory structure, volumes can be initially created on a disk by using the 
File Manager's Initialize command. The Initialize command: 

1. Formats the disk (If necessary). 

2. Records its assigr^d volume name of 143 to 32 ct^oracters. 
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3. Creates Us initial empty directory (also called a catalog). 

4. Mounts Uie initialized disk. 

When an object is created on a dlsk^ its file name of up to 32 characters is 
entered in the disk's directory. File names must be unique within a volume so 
that every object can be clearly identified. 

2A2 File Specifien 

Within the Workshop^ file specifiers are used to identify the volume^ device^ 
file^ or set of files an operation applies to. The diagrams that follow show 
the makeup of a file specifier and its components. 
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wild-caid-spec 




A physical device name refers to a specific hardware device or port, whether 
or not there is actually anything connected or nnounted there. When a device 
is block-structured and mounted, its physical device name can be used in a 
file specifier instead of the disk or diskette's volume nanr«. Since sequential 
devices are not mass storage devices, they never have volume names. The 
only way to specify them is to use their physical device names followed by 
dummy file names; for example, "-RS232A-X*'. Logical devices are also not 
mass storage devices and do not have volume names. They can be referred to 
by their logical device names only. 

Z4w3 The Working Directory and the Prefix 

Sometimes, specifying the same volume name or physical device name again 
and again is inconvenient With the File Manager's Prefix command you can 
establish a particular volume as the OS's working directory. Otherwise, the 
default working directory is the volume the system was booted from. If a file 
specifier omits the volume or physical device name, the file or set of files is 
assumed to be in the working directory. For example, if the working directory 
is -MYDISK, the file specifier PROGRAMLGBJ refen to the same file as 
-MYDISK-PROGRAMLCBJ. 

-UPPER The upper diskette; drive l. 

-LOWER The lower diskette; drive 2. 

-P/V^^'ORT ProFile attached to the parallel connector. 

-SLOTimCHANn ProFile attached to the Parallel interface Card in slot m, 

channel n (where m is a slot between 1-3, and n is 

channel 1 or 2). 



2-10 



MonKshQp User^ Guide The FJle Manager 



NOTE 

To avoid confusion within the system, do not assign a device name to a 
volume. 

There are also two serial devices, -RS232A and -RS232B. These provide 
access to external RS232 devices. 

There are three logical devices that can be used for input and output These 
devices are: 

-CONSOLE Used for output to the screen and input from the keytx)ard. 
The actual device that is used as the console can be 
changed by the Console command in the System Manager. 
See Section 3.2 for information on the Console command. 

-PRINTER Used to output to the printer. The physical connector that 
the printer is connected to is set by the Preferences tool, 
described in Section 3.3.3. If you have more than one 
printer, the one that will be used is specified by the 
DefaultPrinter command described in Section 3.2. 

-KEYBOARD Used as a nonechoing input device from the keyboard. This 
is the keyboard on the console device. 

Certain types of files in the system have standard fJJe extensions. These 
extensions make it easier to keep track of the different types of files. These 
file extensions are: 

.TEXT This indicates a text file in the format created by the Editor. 

.OBJ This indicates an object code file. Object files are created by 
the code Generater, the Assembler, and the Linker. Object files 
created by the Linker are executable. 

.1 This indicates an intermediate (I-code) file produced by the 
Pascal Compiler. The Generate command converts an 
Intermediate file into an object code file. 

.LIB This indicates a library directory. 

Z5 Uing Wild Card Characten 

Wild card characters allow you to specify a set of files to operate on. The 
command is performed on all files whose pathname matches the set specified. 
Wild card characters are "-", "T, and "9'. Only one wild card character can 
appear in a file specifier. These characten are used as follows: 

stilngl-stiing2 

The "-" character stands for any sequence of zero or more characters that 
can be ignored in the search. The surrounding strings (stringl and string2) 
must be matched exactly, ignoring case. Either or both strings can be null. 
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Here are some examples of using the "-" wild card character as a source file 
name: 

ds-.text All files beginning with ds and ending In .text 

-.obj All files ending with ,obj. 

All files. 

When ••-" Is used In a destination file name. It Is replaced with the characten 
that were matched by a wild card In the source file. This enables you to do 
operations like change the name of a list of files as they are copied. Here 
are examples of using •*-" as a destination file name: 

ds-.text to bu/ds-.text Change all files starting with ds and en0ing 

with .text so they begin with bu/. 

qd.- to quickdraw.- Change all files starting with qd to begin with 

quickdraw. 

strlngl?string2 

The "?" character is the same as the "-"^ except that the system asks you to 
confirm each file name before performing the operation. The "?" wild car0 
can be used only in a source string. 

When you use a "?" in a source specifier, you are presented with a list of files 
that match it You can move backwards and forwards through the list by 
using the up and down arrows on the numeric keypad. Press Y beside every 
file that you want to be processed. When you have selected all the files you 
want, press [RETURN]. The operation will then be performed on the files yog 
selected after confirmatioa 

When using the List conrvnand, you cannot use the "?" wildcard in response to 
the prompt for a volume name. 

strlngl$strlngZ 

The "$^' character can stand for part of a destination file name only. It is 
replaced by the entire source file name. For example, if you have the source 
files matching ds-.text: 

dsfnr^r.text 
dssmgr.text 
If the destination expression is bk$, the output files will be: 

bkdsfmgr.text 
bkdssmgr.text 

Contrast this with tr« output expression Wc-.text, which results In: 

bkfmgr.text 
bksmgr.text 
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Hint You can adopt conventions for naming files tnat pretend there is a 
hierarchical file system: for example, 

Source/Fl-text 
Source/F2.text 
Source/XYZ.text 

Z6 How Do I List Existing FUes? 

You can use either the List command or the Names command to list existing 
files. The Names command executes much faster than the List command, but 
it gives you only the file names. 

1. If you are not in the File Mcnager subsystem, enter it by typing F in 
response to the Workshop command prompt 

2. Execute the List commarxj by pressing L, or the Names command by 
pressing M 

3. If you want to list an entire volume, enter the pathname of the volume or 
device. If you want to list only a certain set of files, enter a wild card 
expression or pathname describing the files to be listed. (The "?" wildcard 
cannot be used in response to the List command prompt for a volume 
name.) If you want a listing of the default volume, press [RETURN]. 

The listing produced by the List command is explained in Section 2.3.4. 

You can send a copy of the directory to a file by following the specification 
with a comma and then the name of the file to send the directory to. For 
exarqple, 

-paraport-bk/-,foo.text 

sends the directory to foo.text 

For more information on wild card characters, see Section 2.5 in this chapter. 

Z7 How Do I Copy a File? 

You can Copy a file and leave the original file intact, or you can Transfer a 
file, which copies the file, then deletes the original file. To copy a file: 

1. If you are not in the File Manager subsystem, enter it by typing F in 
response to the Workshop command prompt 

2. Press C to start the Copy command. (Press T, for Transfer, if you want 
the original file to be deleted after the copy operation.) 

3. Enter the pathname of the file you want copied. Press [RETURN). 

a. Enter the pathname you want the file to be copied to. Press [RETURN). 
The file is copied or transferred as you specified. 
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If you want to copy a number of files with similar names, or all the files on a 
volume, you can use wild card characters. See Section 2.5 for more 
information on using wild cards. Wild cards can also be used to rename all 
the copies of the selected files. 

The following are examples of copy and transfer operations: 

Copy from what existing f ile(s)? myprog 
Copy to what new file? -backup-$ 

(This copies the file myprog on the working directory to the volume 
-backup with the same name, myprog.) 

Copy from what existing file(s)? ds= 
Copy to what new file? -backup-$ 

(This copies all files beginning with "ds" on the working directory to 
the volume backup with the same file name.) 

Transfer from what existing file(s)? -osback-osg= 
Transfer to what new file? -oswork-$ 

(This copies all files beginning with "osg" on the volume -osback to the 
volume -oswork using the same file name. When the files have been 
copied successfully, the original files are deleted.) 

You can use a shorthand method of entering the file names by entering both 
the source and destination file names, separated by a comma (,) in response to 
the request for the source file. 

Transfer from what existing fileCs)? -osback -osg=, -oswork -$ 

(This is the shorthand venion of the above transfer operation.) 

Copy from what existing file(s)? ds«,-backup-backds= 

(This copies all files beginning with "ds" in the working directory to the 
volume -backup with back inserted as the beginning of each file name.) 

The Backup command is another way to copy files. It is selective, in that 
only different files will be copied. You use the same procedure to backup a 
file as to copy a file. See Section 2.3.1 for more information on the Backup 
command. 

2.8 How Do I Delete a FUe? 
To delete a file: 

1. If you are not in the File Manager subsystem, enter it by typing F in 
response to the Workshop command prompt 

2. Invoke the Delete command by pressing D. 
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3. Enter the pathname of the file you want to delete. 

4. The system asks you to confirm that you want to delete the file. Reply Y 
to delete the file or N to keep it 

If you want to delete more than one file, you can use wild cards. See Section 
2.5 for more infomnatlon on using wildcards. 

2.9 How Do I Create and Use a Vblume? 

A volume can be created on either a diskette or a ProFile disk. Each disk 
c»i contain one volume. Creating a volume on a disk gives the disk a name 
SBTd sets 14) a directory for files. 

1. If you are not in the File Manager subsystem, enter it by typing F In 
response to the workshop command prompt 

2. Press I to invoke the Initialize command. This command asks fon 

a. The device name (upper or lower for a diskette, slot2chan2 or paraport 
for a ProFile, and so forth) 

b. The number of pages to initialize; the default is to initialize the whole 
device. 

c. The volume name. 

d. The maximum nwnber of files on the device; the default Is a good 
value unless you are using a large number of very small files or a few 
very large files. 

The volume is initialized, with an empty directory. (If the device Is a 
diskette, it is first formatted.) The system warns you if you are initializing a 
device that has an existing volume on it, and gives you a chance to change 
your mind before destroying the existing volume. 

After initialization, the device Is automatically mounted so It can be used. 

ZIO How Do I Change the Name of a File or Vblume? 

The Rename command allows you to change the name of any file or volume. 

1. If you are not In the File Manager subsystem, enter it by typing F In 
response to the Workshop command prompt 

2. Execute the Rename command by pressing R 

3. Enter the pathname of the file or volume you want to rename. 

4. Enter the new name. (The same device name Is assumed for a file.) 

The name of the file or volume Is changed. 

You can use the Rename command to change the name of a group of files by 
using wild card expressions. 
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3.1 ThB System Manager , 3-1 

The System Manager allows you to set certain system defaults and set 
up the Lisa configuration^ including external device connections and the 
startup device. 

32 The System Manager Functions 3-1 

The System Manager is activated by pressing s in response to the 
Workshop command line. Its functions are accessed from a command 
line similar to the Workshop command line. 

3.3 The Preferences Tool 3-3 

The Preferences tool allows you to set up the system configuration and 
to specify what external devices are connected. 

3.4 Process Management 3-9 

Tne process management subsystem allows you to make selected 
processes resident^ display the status of all currently existing processes/ 
and remove processes. 
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3-1 The System Manager 

The System Manager allows you to set system defaults and specify the system 
configuration. Using it, you can: 

• Set the Lisa system characteristics such as screen contrast, speaker 
volume, and time lags for repeating keys. 

• Set the configuration of external devices such as disks and printers. 

• Set the default startup device. 

" Set processes to be resident or nonresident, for performance tuning your 
Workshop system. 

• Set which device is to be the console. 

• Redirect output from the console to a file or external devica 
" Monitor all currently existing processes, and remove processes. 

52 The System Manager Functions 

By pressing S in the main comand line, you can enter the System Manager 
subsystem. 

The System Manager command line is: 

SYSTEM-MQR: ManagePiDcess, OutputRedirect, Preferences, Time, Quit, ? 

The System Manager command line works the same as the main Workshop 
corwnand line. Pressing "?" shows you the additional line of commands: 

Console, FilesPrivate, V^idate, OefaultPrinter 

Each System Manager command is described below. 

ManageProcess (M) 

This command puts you into a process management subsystem, which allows 
you to select which processes should be resident for performance reasons, A 
resident process will not be removed from memory when it terminates, so it 
will not have to be reloaded when it is run again. It also allows you to 
display the status of all currently existing processes, and remove processes. 
The process managment subsystem is described in Section 3.4. 

OutputRedirect (0) 

This command allows you to send a copy of all output that is displayed on the 
console to another device, such as the -printer, or to a file on a disk. The 
commaid asks you for the pathname to send the copy to. In order to return 
to displaying only on the console, use the command again and redirect the 
output to the -console device (which is the default). 
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Preferences (P) 

This command starts the Preferences tool which allows you to set up the 
configuration of the Lisa system and the Workshop. The Preferences tool is 
described in Section 3.3. 

TlmeCT) 

This command allows you to set the hardware clock/calendar's date and time. 
See the Lisa Owners Guide for more information on the system clock and 
calendar. The date and time values are used for the creation and 
modification dates on your files^ so tr«y should be kept correct 

Quit(Q) 

This command exits from the System Mgyiager and returns to the main 
Workshop command line. 

Console (C) 

This command allows you to change where the Workshop console is displayed. 
It may be displayed on the main screen^ which is the ctef ault, on the alternate 
screen^ where the Debugger displays^ or on an external terminal connected to 
the RS232A or RS232B connector. When the main or alternate screen is used 
for the console^ output can be stopped and restarted by pressing «-S. If an 
external terminal is used with XOn/XOff processing enabled^ then control-S 
stops output and control-Q restarts it. 

The console can be moved to the alternate screen when you run a graphics 
progrstfn to prevent output from writelns from appearing on the gr^ics 
screen (the main screenX You can display either the alternate or the main 
screen by pressing OPTION-ENTER. When the console is moved to the 
alternate screen, both the console output (writelns) and the Debugger output 
will be mixed together on the same screen. 

FilesPilvale (F) 

This command enables or disables the selection of private system files. The 
Lisa Office System uses file names beginning with the "f character for its 
tools and documents, and the Workshop user should rarely be concerned with 
such files. These files are called "private". When selection of private files is 
disabled (the default), the Workshop File Manager's wild card mechanism will 
exclude them from its selections unless the file specifier explicitly includes 
the leading "f. 

There are just a few private files which are used by the Workshop (for 
example, {Tll)menus.text). You must enable the selection of private files if 
you want a single file specifier to refer to the entire set of workshop system 
files. 
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validate (V) 

This command is used to set up how much verifying you want the Workshop to 
do for you. There are two values you can set with this command. The first 
is whether or not to verify file copies. The system verifies a copy by 
comparing the original file with the copy to be sure they are the same. The 
default is to never verify. You should have no reason to verify unless you 
suspect something is wrong with your disk. The secwid value you can set is 
whether or not your selections for File Manager commands are verified. 
Selections are verified by listing the file names and asking you to confirm the 
operation. 

DefaultPrinter jp) 

This conmaTd is used when you have more than one printer connected to your 
Lisa It tells the system which one will be the -printer logical device. It 
first gives you a list of all the physical devices that have been configured by 
the Preferences tool as printen, then asks you for the device name of the 
printer you wish to refer to as -printer. 

33 The Preferences Tool 

Start the Preferences tool by pressing P in response to the System Manager 
command line. It displays a window with four checkboxes and a tools menu. 
The Preferences display is shown in Figure 3-1. 
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Figure 3-1 
The Prefferences Window 

After you have finished with the Preferences tool, you can exit back to U« 
System Manager by selecting Quit from the Tools menu. 

The Preferences tool allows you to set up your Workshop system the way you 
want it It contains four sections: 

• Convenience Settings that allow you to regulate screen contrast, the 
speaker volume, and repeat ctelays. 

■ Device Connections that tell the Lisa system what external devices are 
connected. 
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• Startup, which tells the Lisa what device to use as a starttqD device. 

• Workshop which sets up defaults for the Workshop. 

These default settings are stored in parameter memory, a small area of 
memory that is preserved as long as the Lisa is plugged into a working outlet 
aid for 14) to 10 hours when the Lisa is unplugged. If your Lisa is without 
power for longer than this, and the parameter memory is lost, the preference 
settings will be restored from information on the startup disk. 

Any changes made with the Preferences tool change parameter memory 
immediately, but some of them, such as device connections and starti^ 
options, have no effect until the system is booted again. 

The Preferences tool displays a window containing a number of buttons and 
checkboxes. You set the values you want by using the mouse to move the 
pointer to the desired options and clicking. 

Four areas of preferences are described briefly below. More information on 
the first three areas can be found in the Lisa Owners Guicte, Section D, 
Desktop Manager Reference Guide. Select the area you want to view or 
change by moving the pointer with the mouse to the checkbox in front of the 
section nanne and clickir^. 

33.1 Convenience Settings 

The Convenience Settings portion of the Preferences tool allows you to 
customize the input and output characteristics of the Lisa These 
characteristics are divided into three sections: Screen Contrast, Speaker 
Volume, and Rates. The Convenience Settings display is shown in Figure 3-2. 
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Figure 3-2 
Convenience Settings 

Screen Contrast 

The contrast portion contains three sections. The fint allows you to select 
the nonnal screen contrast level. Check in a contrast box until the contrast 
level is comfortable. Checking a box immediately changes the contrast 

The Lisa screen automatically dims if no activity is taking place on the 
screen to protect the screen from damage. The delay time before this 
dimming takes place is set with the Minutes Until Screen Dims section. 
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The third section allows you to set the dim contrast level. Checking a box in 
the Dim Level section makes the screen dim to that level until you move the 
nrxause. 

Speaker Volume 

The speaker volume section allows you to set how loud the Lisa's audible 
alerts will be. Checking a box demonstrates the volume by causing two beeps 
at the level you selected. 

Rates 

There are three rates that can be set, two for the keyboard and one for the 
mouse. The fiist is the initial keyboard repeat delay. This is the length of 
time a key must be depressed before it begins repeating. The second is the 
subsequent repeat delay. This is how quickly a key repeats after it has 
started repeating. The third rate is the mouse double click delay. This sets 
the maximum amount of time between two clicks that will be considered a 
double click. These three values should be set for your most comfortable use. 

33.2 Startup 

The Startup display allows you to specify the boot device and the type of 
memory test to be performed on startup. The Startup display is shown in 
Figure 3-3. 

The Startup display lets you select the Lisa system boot device. You are 
given a list of all possible boot devices. Select the one you want 

The Startup display also allows you to select a long or short memory test 
The brief test takes about 20 seconds, the long test takes about ^Q seconds. 

Changes made to the Startup display are put into parameter memory 
immediately, but have no effect until the system is booted again. 
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Figure 3-3 
The Startup Display 

3.3-3 Device Connections 

The Device Connections display allows you to specify what external devices 
are attached to the Lisa When you choose Device Connections, the Lisa 
displays a table showing all the connectors available, and the device (if any) 
that is attached to it. 

To tell the Lisa that you are attaching, removing, or changing an external 
device, check the box for the connector you are using. The Lisa will display 
a list of all devices that can be attached to that connector. Check the 
correct device. If you are removing a device, check No Device. 

For some devices, such as printers, another set of specifications appears. 
Check the appropriate boxes for the device you are attaching. 
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N\)l changes made to the device connections are made immediately to 
parameter memory^ dut they do not take effect until the Lisa is rebooted. 
For the two serial ports^ see the PortConfig utility in Section 11.10. A 
typical device connections display is shown in Figure 3-4. 
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Figure 3-4 
A Device Connections Display 

33.4 Workshop 

The Workshop display, shown in Figure 3-5, allows you to set parameters of 
the Workstx^ system. These parameters will not go into effect until ycKj 
reboot the system. Then tr«y are stored in parameter memory area will stay in 
effect until you change them. 

Note that changes to the memory size affect all other systems (for example, 
the Office System) and will prevent large programs from running. 

With mouse scaling, equivalent X and Y movemonts of the mouse cause 
diagonal cursor movement on the rectangular Lisa screen. Without scaling, 
the cunor would move at a true 45-degree angle on the screen wfen X and Y 
movements of the mouse are the same. 
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Figure 3-5 
The Workitfwp Display 

33.5 T?ie Tools Menu 

The tools menu provides you with two functions: Set all of PM to defaults, 
and Quit Set all of PM to defaults resets parameter memory to the standard 
Lisa defaults. Quit exits from the Preferences tool, and puts a copy of the 
current settings of parameter memory on the disk. 

3.4 Process Management 

The process management subsystem is started by pressing M in response to the 
System Manager command line. This subsystem displays the following 
command line: 

Manage Process: AddResident, DeleteResident, KillProcess^ ProcessStatus^ Quit ? 
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This subsystem is used to control which processes will be resident After a 
resident process runs to completion, it is suspended and retained in memory, if 
possible, rather than terminated and removed from memory. This allows it to 
restart faster, because the process does not have to be recreated. For 
exstfnple, if you are often using the Pascal Compiler and the Editor, you can 
improve the performance of your Workshop system for these applications by 
making the Compiler and the Editor resident This will allow much nnore 
rapid shifting between the two. 

See the OperaUng System Reference Manual for the Lisa for more 
information on processes 

AddResident (A) 

The AddResident command adds a process to the list of processes that are 
resident. You supply the file name of the object file that you want to be 
made resident the next time it is executed. 

DeleteResident (D) 

The DeleteResident command removes a process from the list of resident 
processes, but does not kill the process if it is currently running. 

KillProcess (hg 

The KillProcess command terminates a currently existing process, including a 
background process, but does not remove it from the list of resident processes. 

ProcessStatus (P) 

The ProcessStatus command gives you information about all currently existing 
processes. It provides the following information: 

Pathname The name of the processes object file. 

Proc8ss_ID The unique identifier assigned to the process. 

state The current state of the process: Active, Suspended, or 

Waiting. 
Resident Tells you if this is a resident process. 

Quit 

The Quit command exits from the process management subsystem back to the 
System Manager command line. 
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4.1 "me Editor 4-1 

The Editor is used to create and modify text files. 

HJZ using the Editor 4-2 

start editing by pressing E in response to the command prompt The 
Editor creates a new file or edits an existing one. Operations are 
provided in five menus: File^ Edit^ Search, Type Style, and Print. 

4.3 Selecting Text 4-4 

The mouse is used to select text and to move the insertion point 

4.4 Scrolling and Moving the Display 4-5 

The display can be scrolled by using the scroll bar on the right side of 
the window. The window can be moved by clicking in the title bar. 
The size of the window can be changed by using the size control box 

4.5 The File Functions 4-6 

The file functions are used for retrieving and saving text files. You 
can also save or revert to a previous version and exit the Editor. 

4.6 The Edit Functions 4-8 

The three basic edit functions are cut paste, and copy. The Edit menu 
also gives you functions to adjust text to the left and right, and to set 
tabs. 

4.7 The Search Functions 4-9 

Search gives you functions to find text strings in the file, and 
optionally replace them. 

4.8 TTie Type Style Functions 4-11 

The Type Style menu enables you to change the font that the file is 
displayed and printed in. 

4.9 TTie Print Functions 4-12 

The Print menu enables you to print the file, and to specify the format 
it should be printed in. 
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4.1 Tiie Editor 

The Editor is used to create and modify text files. These files can be used 
for many purposes including input to the language processors and as exec files. 

If the file you are editing is too big to fit on the screen, a portion of the file 
is displayed. This "window" into the file can be moved to display any part of 
the file you want. An example of the Editor display is shown in Figure H-l. 
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Figure 4-1 
The Editor Display 

The basic editing operations are inserting characters, cutting a portion of the 
text, and pasting text into a new location. Text that is cut goes into a special 
window called the Clipboard. Text on the Clipboard can be pasted into any 
place in the file or into another file. 

All editing action takes place at the insertion point The insertion point is 
marked by a blinking vertical line where the next character will be placed. 
Any characters typed or pasted from the Clipboard are inserted at this point. 
This is true even If the insertion point is not currently displayed in the 
window. The window is automatically scrolled to show the insertion point. 
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NOTE 

The Editor is memory based This means that there is a physical limit 
on the size of the file that can be edited. If a file is too big to edit, 
it should be split into more than one file of manageable size. The 
FileDiv and FileJoin utilities can be used for this. They are described 
in Chapter 11. 

The mouse is used to scroll the text in the window, move the insertion point, 
select text to be cut or copied, point to menus, and select items on menus. 

4^ Using the Editor 

Start the Editor by pressing E in response to the Workshop command prompt. 
The Editor prompts you for a text file name. If you want to edit an existing 
file, enter its name. If you want to create a new file, choose Tear Off 
Stationery from the File menu. The Editor prompts you for the stationery 
name. Press [RETURN] for the default, which is blart< paper, or enter a name. 
For more information on stationery, see Section ^.2.3. 

The file that you are working on is called the active document You can have 
several documents open and accessible at any one time, but only the active 
document can be edited. The active window is indicated by a darkened title 
bar and scroll bars, and is always on top of all the windows. 

To leave the Editor, select Exit from the file menu, and you will return to the 
Workshop command line. 

4^.1 Editing Gpeiations 

The basic editing operations are cut, paste, and copy. To cut or copy text, 
you must first select the text to be cut or copied, select text by moving the 
mouse while holding down the button. See Section 4.3 for conplete 
information on selecting text Text that is selected and then cut is removed 
from the active document and placed in a special window called the 
Clipboard. Text that is copied is placed on the Clipboard and also left in 
place in the active document. 

The contents of the Clipboard can be pasted at any point in the active 
document by placing the insertion point where you want the text inserted and 
choosing Paste from the Edit menu. 

ti22 The Menus 

Operations are provided in five menus: File, Edit, Search, Type Style, and 
Print The File menu is used to access documents and stationery, to put away 
files, and to exit the Editor. The Edit menu contains the editing operations. 
Search provides for finding strings in the active document The Type Style 
menu selects the font for document display. The Print menu controls printing. 
Each of these menus is described in more detail in the sections that follow. 
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You select an operation from a menu by moving the arrow pointer to the 
menu name on the menu bar md holding down the button. The menu is 
displayed. Choose the menu item by moving the mouse down until the item 
you want appears in reverse video. Releasing the mouse button starts the 
operation. 

/L23 Creating and Using Stationery 

Stationery for a special purpose, such as a letterhead, can be created with the 
Editor. Stationery is just a regular text file containing the desired text To 
use any stationery other than the default blank paper, choose Tear Off 
Stationery from the File menu, and type the name of the document containing 
the stationery when it asks you for the stationery name. 

To create stationery, make a document containing the text you want on the 
stationery. Save this document on the disk. To use this stationery, choose 
Tear Off Stationery from the Edit menu, and give it the file name of the 
stationery you created. 

4.2.4 Editing Multiple Files 

More than one document can be open at one time, but only one document is 
the active document To read in a document when you already have an active 
document, choose Open from the File menu. It asks you for the document 
name. The new document is read into a window on the screen and becomes 
the active document To make another document that is already open the 
active document, use the mouse to move the pointer into a portion of that 
document and click the mouse button. If you have several documents open, 
you might have to move some out of the way. 

This capability of working with more than one document at a time can be 
used to copy text from one document to another by using the following 
sequence of operations: 

• Open the document containing the text you want to copy. 

• Select the text you want to copy and choose Copy from the Edit menu. 
This places a copy of the text onto the Clipboard. You can use Cut if you 
want the text to be removed from its original file. 

• Open the document you want the text to be copied to. It becomes the 
active document. 

• Place the insertion point at the place you want the text to be inserted, or 
select the text you want to replace. 

• Choose Paste, which copies the text from the Clipboard to the active 
document. 

Further information on each of these operations can be found in the sections 
that follow. 
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4.3 Selecting Text 

The basic editing functions are cut, copy, and paste. Before you can cut or 
copy text, you must select the text to be cut or copied. Before you paste, you 
place the insertion point where you want the text to be placed. You select 
text and place the insertion point by using the mouse to move the pointer on 
the screea 

Within an active document, the pointer will have one of three shapes: 

Text pointer in a document 

Arrow pointer for menus and scroll bars 

Hourglass when an operation will take over 20 seconds 

Use the mouse to move the pointer on the screen. The shape of the pointer 
changes when you move in and out of the document window. 

Within the window, the text pointer is used to move the insertion point and to 
select text. 

In selecting text, you can select characters, words, or lines. You can also 
select any number of characters, words, or lines. Selected text is displayed in 
reverse video. 

43.1 Moving the Insertion Point 

The insertion point is indicated by a blinking vertical line where the next 
character will be inserted. All insertion, whether from typing or pasting, 
takes place at this point in the file, even if it is not visible in the window. 

To nnove the insertion point, move the pointer to where you want it to be and 
click. Note that the insertion point moves when you select text 

43J2 Selecting ChaiBcters 

To select characters, move the text pointer to the beginning of the characten 
you want to select, press and hold the mouse button while moving to the last 
character you want to select 

An alternate way of selecting characten, which is especially useful when 
selecting a large block of text, is as follows. Move the pointer to the 
beginning of the text you want to select and click the mouse buttoa Then 
move the pointer to the end of tf« text you want selected and shift click. 
Shift click means to hold down the shift key on the keyboard and click the 
mouse buttoa You can use the scrolling controls to display the end of the 
text you want selected if it is too big to fit in the window. 

4w33 Selecting Words and Lines 

To select a word, move the pointer into the word aid click the nnouse button 
twice. To select a line, nnove the pointer into the line and click the mouse 
button three times. 
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To select multiple words or lines, click the mouse button the required number 
of times, and hold. Move the pointer to the last word or line you want 
selected and release. If you double-click, and hold down the mouse button 
while you move the insertion point to the left or right, the selection expands 
or contracts by words. If you triple-click, and move the insertion point up or 
down, the selection expands or contracts by lines. 

An alternate method, especially useful when you want to select more text 
than will fit in one display window, is as follows. Click the required number 
of times to select the first word or line. Scroll the window if necessary to 
display the last item you want selected. Move the pointer to the last item 
you want selected, shift click, and the entire block of text becomes selected. 

0.4 Adjusting the Amount of Text Selected 

To change the amount of text selected, move the pointer to the position that 
you want the selection to extend to and shift click. This can be used to 
either expand or contract the selection. 

tm Scrolling and Moving the Display 

When a document is longer than will fit into the display window, only part of 
the document is displayed at one time. You can change what part is 
displayed by "scrolling" through the display. The vertical bar on the right side 
of the active window is the scroll bar. An example of a text window showing 
the scroll bar is in Figure 4-1. 

The display window can be changed in size and moved on the screen. This 
enables you to have multiple documents displayed on the screen. These 
operations are done using the title bar and size control box as explained in 
Section 4.4.2. 

4.4.1 Scrolling the Display 

There are three ways of moving the display window through the document 
The first is by using the elevator. The elevator is the white rectangle in the 
scroll bar. Its position in the grey portion of the scroll bar indicates the 
relative position of the currently displayed text window in the document. If 
the elevator is near the top, you are near the beginning of the document. If 
it is near the middle, the text displayed in the window is near the middle of 
the document, and so on. To change the position of the text window, you cshi 
move the pointer into the elevator, click and hold the mouse button down 
while you move the elevator to the position in the document you want to 
display. When you release the button, the display will show the new position. 

The second way of moving the window makes use of the view buttons. The 
view buttons are the boxes at each end of the scroll bar. If you move the 
pointer to a view button and click, the display moves one windowful toward 
the beginning or en0 of the document, depending on which button you clicked. 
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The third way of moving the window uses the scroll arrows, which are just 
above and below the view buttons. If you move the anow pointer to the 
bottom scroll arrow and click, the display window will move one line toward 
the end of the document If you hold the button down, the window will 
continue to move a line at a time until you release it. The upper scroll arrow 
works the same way, except it moves the window towards the beginning of the 
document 

tUi2. Moving the Window 

You can move the window on the screen and change its size. This lets you 
display multiple documents on the screen. You can make any visible window 
be the active window by moving the pointer into it and clicking. 

To move a window, move the pointer to the title bar, press the nnouse button 
and hold it while you nrove the window. When you release the button, the 
window is redisplayed at the new location. 

To change the size or shape of the active window, move the pointer to the 
size control box, press the button, and move the pointer until the window is 
the right size and shape. Release the button and the resized window will be 
displayed. The size control box is the box in the lower right hand corner of 
the window. Only the active window can be resized. 

4.5 The File Functions 

The file menu provides functions for reading in and writing out documents, 
updating documents, copying documents, and exiting the Editor. The File 
menu is shown in Figure a-2. Each function is explained below. 

Save & Put Away 

This writes out the active document and closes it 

Save a Copy in . . . 

This writes out a copy of the active document to another document name. 
You are prompted for the name of the document to write to. 

Save & Continue 

This saves all changes made so far by writing out the document to disk, 
without closir^ the document 

Revert to Previous Version 

This returns the document to the way it was before you started editing it, or 
when you last saved it This is done by reading in the document from the 
disk. 
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Figure 4-2 
The File Menu 

Gpen . . . 

This tells the Editor to get a new document. It prompts you for the document 
name, then reads it in and makes it the active document The Editor supplies 
the .TEXT extension on the file name. If the file name that you want does 
not end in .TEXT, you must end the file ngHne with a period. See Section 1.5, 
The Workshop User Interface. 

Duplicate . . . 

This enables you to read in a copy of an existing document to edit into a new 
document. It is read in with the ctefault name "larititled" 

Tear Off Stationery 

This gets a new piece of stationery and makes it the active document See 
Section 4.2.3 for more informaticMn on stationery. The stationery is given the 
default name "untitled". 

Exit Editor 

This first asks you if you want to put away any modified documents. If you 
answer yes, they are written out to disk. Then it exits the Editor. If you 
make the Editor resident, you can exit and restart the Editor without losing 
any information between invocations. Section 3.4, Process Management, gives 
instructions on how to make the Editor resident 
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4.6 The Edit Functions 

The Edit menu provides editing functions and tab setting. It is shown in Figure 
4-3. 

The three basic edit functions are cut, paste, and copy. These make use of 
the special window called the Clipboard. The Clipboard can hold one piece of 
text. Text is put into the Clipboard by selecting it in the active document, 
and either cutting it or copying it. Text is copied from the Clif^oard and 
inserted at the insertion point with the paste operation. 
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Figure 4-3 
The Edit Menu 

For example, to move text from one place in a document to another: 

1. Select the text to be moved. 

2. Choose Cut from the Edit menu. The text is removed from the active 
document and placed on the Clipboard. 

3. Place the insertion point where you want the text to be. 

4. Choose Paste from the Edit menu. The text on the Clipboard is inserted 
at the insertion point. 

The Edit menu also enables you to adjust selected text left or right by 
inserting or deleting spaces, and to set tabs. 
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Some edit functions can also be done by holding down the # key and pressing 
another key. The key that corresponds to each function is shown in the Edit 
menu, as you can see in Figure tt-3. 

Undo Last Change 

This command puts the document back to the way it was before the previous 
operation, if possible. You will receive a warning message if the last 
operation cannot be undone. 

exit 

Cut places a copy of the currently selected text onto the Clipboard and 
removes the text from the active document. You can also Cut by pressing the 
X key while holding down the % key. 

Copy 

Copy places a copy of the currently selected text onto the Clipboard, but 
does not remove it from the active document. You can also Copy by pressing 
the C key while holding down the « key. 

Paste 

Paste inserts a copy of the text on the Clipboard at the insertion point in the 
active document If a section of text is selected. Paste replaces it You can 
also Paste by pressing the V key while holding down the « key. 

Shift Left 

Shift Left moves selected text left by deleting a single space from the left of 
each line. It does not delete any characters other than spaces. It is most 
often used to adjust the left margin of a block of text You can shift left by 
pressing the L key while holding down the * key. 

Shift Right 

Shift Right is similar to Shift Left, except that it moves the selected text to 
the right by inserting spaces at the beginning of each line. This can also be 
done by pressing the R key while holding down the # key. 

Set Tabs . . . 

Set Tabs enables you to set the spacing of the tab stops. 

Select All of Document 

This command selects the entire document. You can also select the entire 
document by pressing the A key while holding down the # key. 

4.7 TTie Search Functions 

The Search menu gives you the ability to search for a text string in the 
active document The basic operation is Find, which locates the next 
occurrence of the string and selects it Find & Paste All replaces each 
occurrence of the string with the contents of the Clipboard. Several options 
are provided to specify how the match is to be found. The Search menu is 
shown in Figure a-a. 
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Figure 4-4 
TTie Search Menu 

All searches start at the insertion point, and go to the end of the document. 
There are three search operations in the Search menu, as follows: 

Find ... 

Find prompts you for the string to search for, then finds the next occurrence 
of the string. If a match is found, it is selected. If not, the system tells you. 
The Find command can also De executed Oy pressing the F key while holding 
down the « key. 

Find Same 

Find Same repeats a previously specified Find, and selects the next occurence 
of the string. You can do a Find Same by pressing the S key while holding 
down the ll key. 

Find & Paste AU 

Find & Paste All finds all occurrences of the specified string from the current 
insertion point to the end of the file, and replaces each of them with the 
contents of the Clipboard. 

The other four items in the Search menu tell how a match is to be found. 
There are two areas to describe: searchir^ for tokens or characters, and if 
case must be matched. The options currently in effect have a check mark in 
front of them. To change the option, you choose a new ore. 

The first set of options tells whether to search for tokens or to search 
literally: 
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Separate Identifiers 

When Separate Identifiers is chosen, the search operation looks for a "token" 
or word to match the search string. A token is a word bounded by spaces. 

All Occurrences 

When All Occurrences is chosen, the search operation matches any string 
containing the same characters, even if it is only part of a word. 

The next options indicate if case is significant in finding a match: 

Cases Need Not Agree 

When Cases Need Not Agree is chosen, any string with the same characters is 
a match, regardless of whether they are in uppercase or lowercase. 

Cases Must Agree 

When Cases Must Agree is chosen, the string with the same characters, and 
matching case, is selected. 

The Type Style Functions 

The Type Style menu enables you to change the display font. The Type Style 
menu is shown in Figure tt-5. A check appears in front of the font in which 
the document is currently displayed. You can change the font by selecting 
another font from the menu. 

The font selected affects how many characters can be displayed on a line, and 
whether or not the display is proportionally spaced. When a document is 
printed, it is printed in the same type style it is displayed in, if that type 
style is available on your printer. 
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Figure 4-5 
The Type Style Menu 
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4.9 The Print Functions 

The Print menu provides functions for printing a document You can print all 
or part of a document, choose what form of footers are to be printed, specify 
if Pascal keywords are to be emphasized, and tell what type of printer is 
being used. The Print menu is shown in Figure 4-6. 

The Print functions are as follows: 

Print All of Document 

The Print All of Document command prints the entire document 

Print Selection 

The Print Selection command prints only the currently selected portion of the 
document. 

Both of the print commands wait if the printer is not ready. 

The remaining options in the Print menu involve how the print is to be 
performed. They are organized into three sets of two options. The currently 
selected option in each set is indicated by a check mark. You can choose any 
combination of options you want 
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Figure 4-6 
The Print Menu 

The first options control what type of footers are printed at the bottom of 
the page. 
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Full Fcxjters 

When Full Foolen is chosen, each page printed has a footer consisting of the 
document name, the page number, and the date. If the document is less than 
one page long, no footer will be printed. 

Page Number Only 

Choosing Page Number Only results in only a page number on the bottom of 
each printed page. If the document is less than one page long, no page 
number will be printed. 

The next options are used for printing Pascal programs. 

Plain Keywords 

Choosing Plain Keywords causes Pascal keywords to print as normal text. 

Differentiated Keywords 

Choosing Differentiated Keywords causes Pascal keywords to print with 
underlining. In addition, the read procedure, write procedure, and other 
standard Pascal procedures and functions are underlined. 

You choose the type of printer to print on with the next options. Select the 
type of printer you have attached to your Lisa: Dot Matrix Printer or Daisy 
Wheel Printer. 
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5.1 Ttie Pascal CX)mpiler 5-1 

The Pascal Compiler translates Pascal source statements into object 
code. This translation is in two steps. The source statements are first 
translated into Intermediate code (I-code), then the l-code is translated 
into object code. 

5J2 Using the Pascal Compiler 5-1 

The Compiler expects as input a text file containing a Pascal program. 
The Compiler translates source code into intermediate code (I-code), 
then the code generator translates I-code into object code. 

5.3 TTie Pascal Compiler Commands 5-2 

You enter Compiler commands into the Pascal source file. They 
provide for symbolic debugging information and conditional compilation. 

5.4 The Pascal Run-Time Environment 5-3 

This section explains how to use the PASLIBCALL unit^ which provides 
some special system functions to Pascal programs. It also explains how 
the Pascal heap operates. 
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5.1 The Pascal Compiler 

The Compiler translates Pascal source statements into object code. This 
translation is done in two steps. The first step, parsing, converts the program 
into semantically equivalent tree structures called I-code. The second step 
translates the resulting 1-code into machine language. 

A complete definition of Lisa Pascal is found in the Pascal Refewnce Manual 
for the Lisa. A Pascal program can call assembly language routines. More 
information on assembly language is in Chapter 6 of this manual. 

The Operating System provides a number of routines that can be called from a 
Pascal program to perform various system functions. These routines are in the 
SYSCALL unit, which is described in the Operating System Reference M&iual 
for the Lisa 

The Pascal run-time support routines are in the library lOSPASLlB.OBJ. The 
support routines for floating point operations are in IOSFPLIB.CBJ. After 
generating the object code, it is necessary to link the program with 
lOSPASLIB.CBJ before you can run it. If you are using real numbers, you must 
also link with IOSFPLIB.OBJ. For information on how to link the program, see 
Chapter 7 in this manual. 

5.2 Using the Pascal Compiler 

The Compiler expects a text file containing a Pascal source program as input 
You can create this text file using the Editor. 

When you have prepared a source program, use the Compiler to translate it 
into object code. Start the Compiler by pressing P in response to the 
Workshop commard prompt The Compiler first asks: 

Input file[.TEXT] 

Type the name of the file that contains the source program. You do not need 
to add the .TEXT extensioa The Compiler then asks: 

List file[.TEXT3 

Type the name of the file ttiat you war»t the listing to go to, or press 
[RETURN] if you don't want a listing. You can display the listing on the 
console by using the -console pathname. The Compiler next asks you where 
to store the I-code form of the program: 

I-code file[<input naTie>][.I] 
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If you want the I-code to te stored in a file with the same narie as the 
source file, but with a .1 extension instead of the .TEXT, just press [RETURN]. 
If you want another name, type the name and press [RETURN} 

After the last input, the Compiler translates the program into I-code and 
stores it in the I-code file. If there were any errors, they are displayed in 
the listing file, or on the console if there is no listing file. When a message 
is displayed on the console, you are given a choice of aborting the corrpile by 
pressing [CLEAR], or continuing the compilation to look for more errors by 
pressing the space bar. A few erron give additional information after you 
press the space bar. Enors can also be placed in a separate error file by 
using the $E Compiler command. 

5J2.1 Using the Code Generator 

To translate the I-code into object code, press G in response to the Workshop 
command prompt. The code generator first asks: 

Input file [.I] - 

Type the name of the I-code file. You do not need to add the .1 extension. 
The generator then asks: 

Output File [<input naine>][.OBO] - 

To accept the default name, press [RETURN], If you want a different name 
for the output file, type the name and press [RETURN]. The .OBJ extension 
will be added to the name for you. 

The output file from the code generator is object code, but it is not 
executable because it does not contain the Pascal run-time support routines. 
The run-time support routines are contained in IOSPASLIB.OBJ, and 
lOSFPLIB.OBJ for floating point operations. These routines must be added to 
the object file by using the Linker. See Chapter 7 in this manual for more 
information on the Linker. 

5.3 The Pascal Compiler Commands 

Compiler commands allow control of code generation, input file control, listing 
control, and conditional compilation. The commands all start with a $, and 
are placed as comments in the source program where you want the command 
to take effect. All the Compiler commands are listed in Table 5-1. A 
complete explanation of the Compiler commands is found in the Pascal 
Reference Manual for the Lisa. 
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Table 5-1 
Pascal Compiler Commands 

Command Meaning 

$1 filename Include contents of filename in this compilation. 

$U filename Search filename for units used. 

$0+ or $C- Turn code generation on (+) or off (-) for a procedure. 

Default $0+ 

$R+ or $R- Turn range checking on (+) or off (-). Default $R-*. 

$S segname Start putting code modules into segment segname. 

$X+ or $X- Turn automatic stack expansion on (+) or off (-). 

Default $X+. 

$D+ or $D- Turn procedure name generation for Debugger on (+) 

or off (-). Default $D+. 

$E filename List Compiler errors in filename. 

$L filename Produce Compiler listing in filename. 

$L+ or $L- Turn source listing on (+) or off (-). Default $L+. 

$DECL list Declare compile time variables. 

$SETC Assign a value to a compile time variable. 

$IFC Begin conditional compilation section. 

$ELSEC Begin ELSE clause of conditional compilation. 

$ELSEC is optional. 

$ENDC End of conditional compilation section. 

5.4 The Pascal Run-Time Environment 

The Pascal run-time environment provides a unit PASLIBCALL which allows 
you to use some special system functions. It also provides special heap 
manipulation functions. 

5A1 The PASLIBCALL Unit 

The unit PASLIBCALL provides you with some additional system functions. In 
order to access the PASLIBCALL routines, you must use the units SYSCALL 
and PASLIBCALL: 

USES 

{$U syscall} SYSCALU 

{$U paslibcall} PASLIBCALL; 

This gives you access to the routines listed below. These routines are 
contained in lOSPASLIB.CBJ, so programs using them require no additional 
inputs to the Lirtf<er. 
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function PAbortFlag : boolean 

This function tells whether or not the «-period key combination has been 
pressed. It enables programs to exit out of long operations. The flag is 
cleared when PAbortFlag is called. If you want your program to stop 
when you press «-period^ you must use this function in the program to 
detect that the key combination has been pressed. For example: 

{This program fragment hangs in an infinite loop until ^-period 
is pressed} 

aborted :=fals8 

Repeat {Halt for # -period. You might want to do other things 
here} 

aborted —PAbortFlag; 

until aborted. 

proc&jure ScreenCtr (contrfun ; integer ); 

This procedure provides standard screen control functions, and enables 
programs to perform screen control without having to to use escape 
sequences. Escape sequences are explained in Appendix C. The parameter 
specifies the screen control function. It is defined in the constants as 
follows, in the PASLIBCALL unit: 

Value 



Function 


Constant 


Decimal 


Hex 


clear screen 


CclearScreen 


1 


1 


clear to the end of screen 


CclearEScreen 


2 


2 


clear to end of line 


CclearELine 


3 


3 


move cunor to home position 


CgoHome 


11 


B 


cursor left one position 


CleftArrow 


12 


C 


cursor right one position 


CrightArrow 


13 


D 


cursor up one line position 


CupArrow 


14 


E 


cursor down one line position 


CdownArrow 


15 


F 



Screen control example: 

{This program fragment clears the screen, and positions the 
cursor on the third line} 

ScreenCtr (CgoHome); 
ScreenCtr (CclearScreen); 
ScreenCtr (CdoimArrow); 
ScreenCtr (CdowiArrow); 
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procedure GetGPrefix (var prefix : pathname); 

This procedure provides your program with the first level prefix setting in 
the File-Mgr in the Workshop. 

procedure GetPrOevice (var PrOevice : ename); 

This procedure returns the corresponding default printer device name so 
that you caBi perform additional device control functions using 
DEVICE_CCMTROL. (The Operating System Reference Manual for the Lisa 
explains the device control call.) The default printer device name is the 
one corresponding to the logical device -printer*. Note that the device 
name returned contains a leading '-*. 

procedure PLINITHEAP (var emunvrefnuro: integer; 

size, delta: longint 
Idsn: integer; 
swapable :boolean); 
where: 

ernum is the error number returned if the procedure has any 

problems making a data segment having a mem_size of 
size bytes. Appendix A contains an explanation of the error 
codes for the Workshqp. 

size is the number of bytes in the heap. 

refnum is the refnum of the hesp, 

delta is the amount you want the data segment to increase when 
the current space is used up. If you use a large heap, use a 
large number for delta. 

Idsn is the logical data segment number used for the heap. The 

default is 5. For more information see the Cperati/y System 
Reference h'^uiual for the Lisa. 

swapable is the boolean that determines if the system can swap the 
heap data segment out to disk if it needs ta 

This procedure can be used when you have special needs; for example, 
when you want to specify your own Idsn or heap size. When you use 
PLINITHEAP, yoj must call it before calling other heap routines. For 
more information on the heap, see Section 5.5. 

5.0^2 The Pascal Heap 

The Pascal heap is one contiguous piece of memory, a data segment, which 
works automatically without any initialization call. See Chapter 11 of the 
Pascal Reference M&%tal for the Lisa for information on the normal heap 
functions. 
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When a Pascal program starts execution, no heap space is allocated (no data 
segment made). On the first call to one of the heap routines or on the first 
PLINITHEAP call, the heap is created with either a default size of 16k bytes 
or the size specified in the PLINITHEAP call. 

PLINITHEAP makes the heap as a private data segment so that the Operating 
System removes it when the process calling PLINITHEAP terminates. Note 
that when the heap is initialized, size and delta are put on 512 byte block 
boundaries. Therefore, if you use the PLINITHEAP call and specify values for 
size and delta that do not fall on block boundaries, the procedure increases 
the values to the next block boundary. 

If the heap runs out of space while it is being used, the size of the heap is 
increased by the default of 16k or the delta specified in PLINITHEAP. The 
default Idsn used is 5. If you want a different Idsn for the heap data 
segment, call PLINITHEAP. Remember that the size of a data segment is 
limited by the Idsn you use. For Idsn 16, you can get only 128k (actually 96k 
safely), for Idsn 15 you cm get only 256k, for Idsn 14 you can get only 38ak, 
and so forth. See the Operating System Reference ManuaJ for the Lisa for 
more information on Idsn's and data segments. 

If swapable is true, the heap is made with disc_size equal to size so the data 
segment is not memory resident This uses up disc_size bytes on the startup 
disc Thre default for swspable is false. When swapable is false, the 
procedure creates a data segment that has a disc_size of (zero), which 
makes it memory resident 

The built-in Pascal heap routines are NEW, MEMAVAIL, MARK, RELEASE, and 
HEAPRESULT. 

• If you call NEW and not enough space is available, the size of the heap is 
increased by either the defajlt of 16k or the delta size specified in 
PLINITHEAP. 

• MEMAVAIL provides the maximun number of words you could ever expect 
to get, taking into account the Idsn you used as well as the amount of free 
space the Operating System currently has available. If another process is 
using memory concurrently, its use of memory also affects MEMAVAIL. 
MEMAVAIL does not show the amount of memory left in the heap's data 
segment alcwie, since the heap's data segment cai grow and shrink over 
time. 

• MARK sets a pointer to the lowest free area on the heap. It is used with 
RELEASE to deallocate variables from tfe hea^D. 

• RELEASE deallocates variables from a marked area of the heap. If you 
release the heap to a point within the original size of the heap data 
segment, the heap data segment is reduced to its original size. More 
information on MARK and RELEASE can be found in the Pascai Reference 
h^nuai for the Lisa. 
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HEAPRESULT returns a if the last l^ap operation was successfuU 
otherwise it contains the Operating System error number indicating what 
failed. A list of the Operating System errors is in Appendix A. 
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6.1 The Assembler 6-1 

The AssemDler translates 68000 assemdly language Into macnine 
language. 

6.2 Using the Assembler 6-1 

The AssemDier accepts a text file as Input and produces a macnine 
language (.OBJ) file as output 

63 Assembler Gpcodes 6-3 

The Assembler opcodes are the standard 68000 opcodes, with a few 
alternate forms for some instructions. 

6.4 Assembler Syntax 6-5 

An Assembler statement consists of an optional laDel, the opcode, and 
one or two operands. The operands can contain expressions. 

6.5 Assembler Directives 6-9 

The Assembler directives provide for procedure and function definition, 
macros, label and constant declaration, listing control, storage 
allocation, and conditional assembly. 

6.6 Communication with Pascal 6-16 

Assembly language routines can be either procedures or functions called 
from a Pascal program. Parameters are passed on the Pascal stack. 

6.7 Assembly Language Examples 6r-2l 

This section provides example assembly language routines Illustrating 
parameter passing and other functions. 
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6.1 Tlie Assembler 

The Assembler is a program that translates assembly language source 
statements into object code. The Assembler accepts a text file containing the 
source statements as input, and produces an object file as output. The object 
file produced must be linked with a Pascal main program before it can be 
executed. 

Assembly language routines are used to implement low level or time critical 
functions. This chapter describes how to use the Assembler, and the syntax of 
assembly language programs. Information on the machine instructions 
available on the 68D0D processor can be found in the Motorola MC68000 
Reference Manual. 

6.2 Using the Assenbler 

To assemble a program, press A from the Workshop command line. Then 
specify the input file (the file that contains your source program) and two 
output files: an optional listing file and the object file (the file that will 
contain the object code produced by it)e Assembler). 

The input file must be a text file containing assembly language source 
statements. You can create this file with the Editor. The output file produced 
is an object file (.CBJ) that must be linked with a Pascal main program to be 
run. 

Any errors in the program will be indicated by messages on the console or in 
the listing file. A complete list of Assembler error messages is found in 
Appendix A of this manual, 

6.2.1 Assembler Options 

When you start the Assembler, the option settings are displayed. You can 
enter the options selection mode by responding to the input file prompt with 
"?". There are two Assembler options: 

P Pretty listing. 

S Print information about available space. 

Each option may be set to ■»• or -: 

+ On 

Off 

When pretty listing is on, the forward referenced labels or offsets are filled in 
with the correct values in the listing. 

After setting options, press [RETURN], and the Assembler asks you for the 
name of the input file. The Assembler then asks you for the name of the 
listing, and the object files. 
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6.2.2 TTie Input File 

The input file is a text file containing Assembler language source statements. 
A file created using the Editor will be in text file format. 

When the Assembler asks you for the name of the input file, type "?" if you 
want to change Assembler options at this time; otherwise type the pathname 
of your source file. File naming is explained in Chapter 2. 

6.2.3 The Object File 

The object file produced hy the Assembler contains a machine code version of 
your source program. The name of an object file ends with XBJ . A raw 
assembly object file is not executable; it must be linked with a Pascal 
program that calls it See Section 6.6 for further information. 

The output file will be an object file which must be linked with a Pascal main 
program before it can be executed. The object file goes to the same volume 
as the input text file was on unless another volume is specified. 

6.2.4 The Listirig File 

The listing file produced by the Assembler contains a list of source statements 
and their machine-language equivalent. If pretty listing is off, all addresses 
for forward referenced labels will be presented in the listing file as asterisks 
(*). If pretty listing is on, the actual values will be filled in. 

Source statement errors are flagged in the listing. Refer to the Appendix for 
a list of Assembler error messages. 

An example of an Assembler listing file is shown in Figure 6-1. Figure 6-2 
shows the same file listed with the pretty list option. 
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one 
label2 



.equ 
.equ 



1 
$20 



41Ffl 
60* ♦ 



OOOE 

0012 

0014 

0014 

0014 

0014 4E71 

0012* 02 

D016I 4E75 

D018| 

)010» 0008 

»18| 19 30 13 

OOIBI 00 



move «label2, dO 

cir dO 

add *one, dO 

beq / II 
bra / 12 




show listing patching 
address filled in 
for backward branching 



done 



data .byte 25, $30, 19 ; odd number of bytes 
.align 2 ; make sure next Instruction 
; is on even 



Figure 6-1 
Assembler Listing 

If you specify a device name such as -printer or -console for the listing file, 
the listing will be printed on that device. If you specify a disk file, the 
listing will be created as a text file; you may then print it by using the Copy 
command in the File Manager command line. 

NonnE 

If you want pretty listing, the listing output must be sent to a file, not 
to a device. Pretty listing is done by making an additional pass 
through the listing file to patch in the forward references. There must 
be enough disk space for two listing files for this operation to succeed. 
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0000 
0000 
0000 
0000 
0000 
0000 
0004 
0006 
0008 

oooc 

OOOE 
OOOE. 
OOOE 
00121 
0014 
0014 
0014 
0014 
0016 
0018 

00 le 

00 IB 



.proc example 



0000 OOOl 
0000 0O2O 


one 
label 2 


.equ 1 
.equ $20 


303C 0020 
4240 
5240 

6700 0OO4 
60F8 


12 


move «label2, dO 

clr dO 

add «one,dO 

beq il ; show listing patching 

bra 12 ; address rilled in 

; Tor backward branching 


41FA 0OO8 
6002 


11 


lea dat\ aO 
bra.s done 

; some more code . . . 


4E71 
4E75 


done 


nop 
rts 


19 30 13 
00 


data 


.byte 23, $30, 19 ; odd number of bytes 
.align 2 ; make sura next instruction 
; is on even 




Figure 6-2 
Pretty Listing 



6.3 Assembler Opcodes 

The 68000 opcodes are described in the Motorola MC68000 Microprocessor 
User's Manual. The Assembler has two variant mnemonics for branches that 
are more indicative of how the instruction is being used after unsigned 
comparisons. These variants are BHS (Branch on High or Same) for BCC, and 
BLO (Branch on Low) for BCS. The default radix is decimal. 

The size of an operation (byte, word, or long) is specified by appending either 
.B, .W, or .L to the instruction. The default operation size is Word. To cause 
a short forward branch (an 8-bit displacement rather than a word 
displacement), append a .S to the instruction. The default branch size is Word. 

Note that the TAS (test and set) instruction is not implemented on the Lisa 
hardware. Using this instruction may cause timing problems. 

Note that the Assembler accepts generic instructions and assembles the 
correct form. The instruction ADD, for example, is assembled into ADD, 
ADDA, ADDQ, or ADDI, depending on the context. 



becomes 



ADD 
ADDA 



D3,A5 
03, A5. 



MOVE, CMP, and SUB are handled in a similar manner. 
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6.4 Assembler Syntax 

This section describes the form in which the Assembler expects an assembly 
language program. The structure of an assembly language program is shown in 
Section 6.4.1. Rules for forming constants^ identifiers, labels, expressions, and 
addressing modes are provided in the following sections. 

6.4wl Stxuctuie of an Assembly Language Program 

An assembly language program contains one or more procedures or functions. 
The structure of an assembly language source file is shown in Figure 6-3, The 
source file contains an (optional) section of operations that doesn't generate 
code. Constants or macros are usually defined here. Next it conains one or 
more procedures (.PROC) or functions (.FUNC). These each contain a sequence 
of directives and code generating operations. A procedure or function ends 
when the Assembler encounters the next .PROC or .FUNC. The .END directive 
is the last statement that is processed by the Assembler. Any text beyond the 
.END is ignored. 

nan code generating operations 

PRCXD (orJTJNC) 

code generating aperatiarts and any tSrectives needed 

PROC 



PUNC 
etc. 

.END 

Figure 6-3 
Structure of an Assembly Language Program 

The directives that don't generate code are: 

.EQU .MACRO .IF .LIST .MACROLIST 

.ENDM .ELSE .NOLIST .NOMACROLIST 

.REF .ENDC .PAGE .PATCHLIST 

.DEF .TITLE .NQPATCHLIST 

6l4.2 Constants 

Constants in the Assembler can be either numeric or string constants. 

6.42.1 Numeric Constants 

Numeric constants in the Assembler can be expressed in decimal, hexadecimal, 
octal, or binary. The default radix is decimaL Numeric constants are 
expressed as follows: 
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Decimal 

Decimal numbers are formed with the decimal digits (0-9). Examples: 

10 
13 
137 

Hexadecimal 

Hex numbers can be expressed in two ways: 

1. Preceed the number with a "$". Examples: 

$FF13 
$127 

2. Follow the number with an "H". Using this form, the number must start 
with a digit (0-9). Examples: 

0FF13H 
195H 

Octal 

Octal numbers are followed by the character "0". Note that this is the letter 
0, not the number zero (0). Examples: 

770 
lOOO 

Binary 

Binary numbers are followed by the character "B". Examples: 

lOllB 
lllOOOB 

6.4.2.2 String Constants 

String constants are delimited by matching pairs of single or double quotes. 
Examples of string constants are: 

"this is a string constant" 

'using single quotes as delimiters lets you include "double" quotes' 

6.4.3 Id^tiflers 

Only the first eight characters of identifier names are meaningful to the 
Assembler. The first character must be alphabetic; the rest can be 
alphanumeric/ period, underbar, or percent sign. 

Examples of identifiers are: 

LOOP 

EXIT_PRC 
NUM 
num6aS6 
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6A4 Labels and Local Labels 

Labels begin in column one. They can be followed by an optional colon. 

Local labels can be used to avoid using up the storage space required by 
regular labels. The local label stack can handle 50 labels at a time. It is 
cleared every time a regular label is encountered. A local label is an • 
followed by a string of decimal digits (0-9). Examples of local labels are: 

@'123 

m 

eP79 

6.0.5 Expressions and Operators 

All quantities are 32 bits long unless constrained by the instruction. 
Expressions are evaluated from left to right with no qDerator precedence 
Angle brackets can be used to control expression evaluation. The operators 
are: 

* positive sign or binary addition 
- unary minus or subtraction 

ones complement (unary operator) 
exclusive or 

* multiplication 
/ division (DIV) 
\ MCD 

I logical OR 

& logical AND 

equal (used only with .IF) 
<> not equal (used only with .IF) 

There is no operator precedence in expressions. For example, in the 
expression 2 + 9 *♦ a, the addition is performed first. To perform the 
multiplication first, rewrite the expression with angle brackets to show 
precedence: 2 + <9 * a>; or reorder the operands: 9*4 + 2. 

6.4.6 Addre^ng Modes 

Refer to the Motorola 68000 manual for detailed information on the 
addressing modes supported by the 68000 microprocessor. Table 6-1 gives a 
summary of the addressing modes including their syntax. 
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Table 6-1 
Summary of Addressing Modes 



Mode Re^ster Syntax Meaning 



0..7 

0.J 

0..7 

0..7 

Q..7 

0..7 

0..7 



1 

2 

3 

4 




Meaning Extra Wdrds 


Data direct 





Address direct 





Indirect 





Postincrement 





Predecrement 





Indexed 


1 


Offset indexed 


1 


Absolute short address 


1 


Absolute long address 


2 


PC Relative 


1 


PC Relative indexed 


1 


Immediate 


1 or 2 



Notes: 

The indexed and PC relative indexed modes are determined Xi'j the opcode. 

The absolute address and PC relative address modes are determined by the 
type of the label (absolute or relative). 

The absolute short and long address modes are determined t^i the size of the 
operand. Long mode is used only for long constants. 

The number of extra words for immediate mode is determined by the opcode 
size modifier (.W or .L). 

NOTE - 

All programs that run under the Lisa OS must be relocatable. 
Addresses should not be absolute. 



6.4.7 Miscellaneous Syntax 
Comments 

A comment in an assembly language program begins with a semicolon. The 
Assembler ignores all characters after a semicolon in a line. Examples are: 

; This is a comment on a line by itself 

CLR.L DO ;coninent after a statement 
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Current Program Location 

The current program location is indicated in assembly language by the symbol 
"*". Examples of its use are: 



JMP * 

JMP *-A 



Loop infinitely 
Junp back A bytes 
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Move Multiple (MOVEM) 

To specify which registers are affected by Move Multiple (MOVEM), specify 
ranges of registers with "-" and specify separate registers with "/*'. For 
example, to push registers DO through D2, Dtt, and AO through A4 onto the top 
of the stack: 

MOVEM. L D0-D2/D4/A0-A4, -(A7) 

Assembler Directives 

Assembler directives tell the Assembler to do various functions besides 
generating executable code. These functions include defining symbols and 
constants, defining macros, doing conditional assembly, and controlling listing 
options. 

The Assembler directives (pseudo-ops) are shown in Table 6-2. 



Table 6-2 
The Assembler Directives 



WrecUve 

.PROC 

.FUNC 

•DEF 

.REF 

.SEG 

.END 

.ASCII 

.BYTE 

.BLOCK 

-WORD 

.LONG 

.ALIGN 

•ORG 



Operands 

<identifier> 

<identifier> 

<identifier-list> 

<identifier-list> 

'<name>' 



'<char-string>' 

<value-list> 

<length>[,value] 

<value-list> 

<value-list> 

<Expr> 

<value> 



.RORG <value> 



Meaning 

begin procedure 

begin function 

make identifiers externally available 

declare external identifiers 

put code of next .PROC in segment 'name' 

end of enUre assembly 

place ASCII string in code 
allocate a byte in code for each value 
allocate length bytes of value 
allocate a word for each value 
allocate a long word for each value 
allign next code on multiple of Expr 
place next byte at <value> relative to 
beginning of assembly 
same as .ORG 



.EQU 



<value> 



.MACRO <identifier> 
.ENDM 



set label equal to <value> 

begin macro definition 
end macro definition 



6-9 



Wo/ksfxp User's Guide 



T/ie Asssfnb/er 



Directive Operands 

.IF <expr> 

.ELSE 

.ENDC 

.LIST 

-NOLIST 

.PAGE 

.TITLE •<title>' 

.MACROLIST 

-NOMACROLIST 

.PATCHLIST 

.NOPATGHLIST 

.INCLUDE <filename> 



Table 6-2 (continued) 
TTe Assembler Directives 

Meaning 

begin conditional assembly 
optional alternate to .IF block 
end conditional assembly 

turn on assembly listing 
turn off assembly listing 
issue a page feed in listing 
title of each page in listing 
turn on macro expansion listing 
turn off macro expansion listing 
turn on patchlist 
turn off patchlist 

include contents of <filename> in assembly 



63.1 Space Allocation Directives 

The space allocation directives are .ASCII, .BYTE, .WC3RD, .LCNG, and .BLOCK 

.ASCII 'string' 

Converts 'string' into the equivalent ASCII byte constants and places the bytes 
in the code stream. The string delimiters must be matching single or double 
quotes. To insert a single quote into the code use double quotes as delimiters. 
Similarly for double quotes: 

.ASCII "don't" ; string containing single quote 

.ASCII 'a "glitch"' ; string containing double quote 

BYTE <values> 

Allocates a byte of space in the code stream for each of the values given. 
Each value must be between -128 and 255. 

.BLOCK <length>[,value] 

Allocates <length> bytes, each filled with the value given. If no value is 
given, a block of zeroes is allocated. 

.WORD <values> 

Allocates a word of space in the code stream for each of the values listed. 
The values must be between -32768 and 65535. 
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For example, 

TEMP .WORD 0,65535,-2,17 

creates the assembled output: 

0000 
FFFF 
FFFE 
0011 

.LONG <values> 

Allocates two words of space for each value in the list. For example, 

STUFF .LONG 0,65535,-2,17 

creates the output: 

00000000 
OOOOFFFF 
FFFFFFFE 
00000011 

<label> .EQU <value> 

Assigns <value> to <label>. <value> can be an expression containing other 
labels. 

.CRG <value> 

Puts the next byte of code at <value> relative to the beginning of the 
assembly file. Bytes of zero are inserted from the current location to 
<value>. 

JRORG 

is similar to .ORG. It indicates that the code is relocatable. Because the 
loader does not support absolute loading, .ORG and .RORG accomplish the 
same function. AJJ addressing must be PC reiatiye. 

6.5^ Macro Directives 

A macro consists of a macro name, optional arguments, and a macro body. 
When the Assembler encounters the macro name, it substitutes the macro body 
for the macro name in the assembly text Wherever "%n" occurs in the macro 
body (where n is a single decimal digit), the text of the n-th parameter is 
substituted. If parameters are omitted, a null string is used in the macro 
expansioa A macro can invoke other macros up to five levels deep. In the 
assembly listing, the listing of the expanded macro code is controlled by the 
options .MACROLIST and .NOMACROLIST. These options are described in 
Section 6.5.5. 
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.MACRO <identifier> 



.ENDM 

defines the macro named <identifier>. The following is an example of a 
macro: 

.HACRO Help 

MOVE %LDO 

ADO D0,%2 

.ENDM 

If "Help" is called in an assembly with the parameters "Alpha" and "Beta", the 
listing created would be: 

Help Alpha,Beta 
« MOVE Alpha, DO 

» ADD DO^Beta 

6.5.3 Conditional Assembly Directives 

The conditional assembly directives .IF, .ELSE, and .ENDC are used to include 
or exclude sections of code at assembly time based on the value of the 
conditional expression. 

.IF <expression> 

Identifies the beginning of a block of source statements that is assembled only 
under certain conditions. If <expression> is false, the Assembler ignores all 
statements until a .ELSE or .ENDC is found. The statements between the 
qDtional .ELSE and .ENDC are assembled if <expression> is evaluted to be 
false at the time of assembly. Otherwise they are ignored. 

<expression> is considered to be false if it evaluates to zero. Any non-zero 
value is considered true. The expression can also involve a test for equality 
(using <> or =). Strings and arithmetic expressions can be compared. 
Conditionals can be nested. The macros HEAD and TAIL given in Section 
6.6.1 provide examples of the use of conditionals. The general form is: 

.IF <expr> 

;asseinbled if <expr> is true 

[.ELSE] /optional 

;asseirtbled if <expr> is false 

!endc 
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6.5.4 External Reference Directives 

Separate routines can share data structures and subroutines by linkage 
between assembly routines using .DEF and .REF. These directives generate 
link information that allows separately assembled routines to be linked 
together. 

.DEF and .REF directives associate labels between assembly routines, not 
between assembly routines and Pascal.The only way to communicate data 
between Pascal and assembly routines is by using the stack. This is done by 
passing the data as parameters in the procedure or function call. Information 
on parameter passing between Pascal and assembly language routines is found 
in Section 6.6. 

DEF <idenUfier-list> 

Identifies labels defined in the current routine as available to other assembly 
routines through matching .REFs. The .PROC and .FUNG directives also 
generate code similar to that generated by a .DEF with the same name, so 
assembly routines can call external .PROCs and .FUNCs with .REFs. 

.PROC Simple,! 
.DEF Alpha, Beta 

BNE Beta 



Alpha HOVE 

RTS 
Beta HOVE 

RTS 
.END 

This example defines two labels. Alpha and Beta, which another assembly 
routine can access with .REF. 

.REF <identifier-list> 

Identifies the labels in <identifier-list> used in the current routine as 
available from some other assembly routines, which defined these identifiers 
using the .DEF directive. 

.PROC Simple 
.REF Alpha 

JSR Alpha 

-EM) 

This example uses the label "Alpha" declared in the .DEF example. 
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When a .REF is encountered, the Assembler generates a short absolute 
addressing mode for the instruction (the opcode followed by a word of O's) and 
a short external reference with an address pointer to the word of O's following 
the opcode. If the referenced label and the reference are in the same 
segment module, the Linker changes the addressing mode from short absolute 
to single-word PC relative. If, however, the referenced procedure is in a 
different segment, the Linker converts the reference to an indexed addressing 
mode (off A5), and the word of zeros is converted into the proper entry offset 
in the jump table. If the referenced procedure is in an intrinsic unit (and 
therefore in a different segment), the lUJSR, lULEA, lUJMP, and lUPEA 
instructions are used. The Linker blindly assumes that the word immediately 
before the word of zeros is an opcode in which the low order 6 bits are the 
effective address. Thus, a .REF label cannot be used with any arbitrary 
instruction. The .REF labels are intended for JSR, JMP, PEA, and LEA 
instructions. 



Default segment name is " " (8 blanks). .SEG "segment name" puts the 

code in segment called "segment name". The .SEG directive takes effect 
when the next .PROC or .FUNC is reached. Thus it is not possible to split one 
procedure into two segments. This is an example of how the .SEG directive 
works: 

.SEG 'namel' 

.PROC A 

{code in PROC A} 

.SEG "name?" 

{code still in .PROC A) {this code will still be in segment "namel"} 

PROC B {code of .PROC B will be in segment •name2"} 

6.5.5 Listing Control Directives 

The directives that control the Assembler's listing file output are .LIST, 
.NOLIST, .PAGE, .TITLE, .MACROLIST, .NOMACROLIST, .PATCHLIST, and 
.NCPATCHLIST. If you do not specify a name for the listing file in response 
to the Assembler's prompt, the listing directives are ignored. 

The default for the Assembler is for .LIST, .MACROLIST, and .PATCHLIST to 
be in effect when the Assembler starts. .TITLE defaults to blank. 

1.IST and .NOLIST 

Can be used to select portions of the source to be listed. The listing goes to 
the specified output file when .LIST is encountered. .NOLIST turns off the 
listing. .LIST and .NOLIST can occur any number of times during an assembly. 
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PAGE 

Causes the next line of the listing file to be printed on the next page. 

.TITLE •<tiUe>' 

Specifies a title for the listing page. <title> can contain up to 80 characters, 
and can be enclosed in either single or double quotes. For example: 

. TITLE ' Interpreter ' 

places the word, "Interpreter", at the head of each page of the listing. 

•PATCHLIST 

Patches the forward referenced labels in the listing. It must be on if you 
want pretty listing. See Section 6.2.4 for more information on pretty listing. 

.NOPATCHLIST 

Turns off patching of forward references. 

.MACROLIST 

Turns on listing of the expanded code from a macro. 

.NGMACRGLIST 

Turns off listing of macro expansion. See Figure 6-4 for examples of macro 
listing. 



00001 

ooool 

0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 

0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0000 
0002 
0002 
0004 
0004 
0008 



5440 
524C 
0443 OOFF 





2 parameters In INC: 
%\ - the amount to add to 

register that is passed as X2 
X2 - register name 
.macro INC 
add ni,« 
.endtn 




paroneters passed to DEC: 
W - amount to subtract 

from register \2 
X2 - register nane 
.macro DEC 
sub »*<1, W 
.endn 


.proc MacroExatiple 
INC 2, dO 

(CO «2,d0 
INC 1, a4 

(€0 «1, a4 
DEC $f f, d3 

SUB «$ff,d3 
.end 


Figu 
Macrc 


re 6-4 
\ Listing 
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6.5.6 File Directive 

.INCLUDE <filenam8> 

Causes the contents of <filename> to be assembled at the point of the 
.INCLUDE. You need not specify the .TEXT suffix. An included file cannot 
itself contain an .INCLUDE statemenL 

6-6 Communication with P^cal 

Assembly language routines must be called from a Pascal program. In order 
to call an assembly language routine, the Pascal program declares the 
assembly language procedure or function to be EXTERNAL. If the assembly 
routine does not return a value, declare the assembly routine as a 
PROCEDURE in the Pascal program. If a function result is to be returned 
from the assembly routine, declare it as a FUNCTION in Pascal and space for 
the returned value is allocated (by the Pascal Compiler) on the stack just 
before the function parameters, if any. The amount of space allocated 
depends on the type of the function. A Longint or Real function result take's 
two words, a Boolean result takes one word with the result in the high order 
byte, and other types take one word. A Boolean result of indicates false, 
any non zero value indicates true. 

NOTE 

Assembly language programs are in read only memory segments. Thus 
they have no data space to write into. Any data space needed must be 
allocated by the Pascal Compiler. A pointer to the space is then 
passed to the assembly language routine. "Writes" to the data space 
are done by pointer references using modes like (Ax), i(Ax), etc. For 
examples of this technique see Section 6.7.5 

In the following example, an assembly language routine is linked to a Pascal 
program. The assembly language routine accepts two integers and returns the 
logical AND of them. The Pascal host file is: 

PROGRAM BITTEST; 
VAR I,J: INTEGERS- 
FUNCTION I^KJ( i, j : INTEGER ) : INTEGERS- 
EXTERNAL; (* external = Assembly language *) 

BEGIN 

i := 255; 

j := 33; 

URITELN (LJ,' AND = '.land (I, J)); 
END. 
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The Assembler file is: 



.FUNC 


lAND 




MOVE.L 


(A7)+,A0 


; return address 


MOVE-i 


(A7)+,D0 


; J 


MOVE.« 


(A7)-,D1 


; I 


ANO.W 


D1,D0 


; I AND J 


MOVE.W 


D0,(A7) 


; put function result on stank 


JMP 


(AO) 




.END 







In the example given above little attempt has been made to make the 
assembly language procedure mimic the structure of a procedure generated by 
the Pascal Compiler. A complete description of this structure requires some 
preliminary discourse. 

6.6.1 TTie Run-Time Stack 

Automatic stack expansion code makes procedure entries a little complicated. 
To ensure that the stack segment is large enough before the procedure is 
entered, the Compiler emits code to 'touch' the lowest point that will be 
needed by the procedure. If we 'touch' an illegal location (outside the current 
stack bounds), the memory management hardware signals a bus error that 
causes the 68Q00 to generate a hardware exception and pass control to an 
exception handler. See the Usa Hardware ManuaJ for more information on 
the memory management hardware. This code, provided by the Operating 
System, must be able to restore the state of the world at the time of the 
exception, and then allocate enough extra memory to the stack that the 
original instruction can be reexecuted without problem. To be able to back 
up, the instruction that caused the exception must not change the registers, so 
a TST.W instruction with indirect addressing is used. 

In the normal case, the procedure's LINK instruction should be preceded by a 
TST.W e(A7), which attempts to reach the stack location that can accomodate 
the static and dynamic stack requirements of the procedure. If the static and 
dynamic stack requirements of your assembly language procedure are less than 
256 bytes, you can assume that the Compiler's fudge factor will protect the 
assembly language procedure, so the TST.W can be omitted. If the 
requirements are greater than 32K bytes, e(A7) may not be sufficient because 
only 16 bits of addressability are available. In this case, the Compiler 
currently emits code that in some cases looks like: 



HOVE.L 

SUB.L 

TST.i 



A7,A0 

#Size,AO 

(AO) 



;#size=dynaralc + static needed 



If the Compiler option D+ is in effect (the default), the first eight bytes of 
the memory area following the final RTS or JMP (AO) contain the procedure 
name, in upper case (produced by the Pascal Compiler). The Debugger gets 
the procedure name from this block, allowing you to use procedure names in 
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the Debugger. The following example shows how an assembly language 
programmer can provide the Debugger with information it needs to perform 
symbolic low level debugging. Note that all procedure names must be in 
upper case to be compatible with the Debugger. 

; ASSEMBLY LANGUAGE EXAMPLE 

DEBUGF .EQU 1 ; true => allon debugging with 

; proc names 

HEAD ~ This MACra} can be used to signal the 
beginning of an asseinbly language procedure. HEAD 
should be used when you do not i»ant to build a stac^ 
frame based on A6, but do want debugging information. 

No arguments 

.MACRO HEAD 

.IF DEBUGF 

LINK A6^«0 ; fancy NOP used by Debugger 

-ENDC 
.ENOH 

TAIL — This MACRO can be used as a generalized exit 
sequence. There are two cases. Firsts if you build 
a stack frame^ TAIL can be used to undo the stack 
frame, delete the parameters (if any) and return. 
Second, if you do not want to build a stack frame 
based on A6, this MACRO can be used to signal the 
end of an assembly language procedure. In either 
case if DEBUGF is true, the Procedurename 
is dropped by the MACRO as an 8-character name. 

Two arguments: 

1) Nunter of bytes of parameters to delete 

2) Procedure_NamB as string exactly 8 characters, 
must be upper case. 

.MACRO TAIL 
UNLK A6 
-IF %1 = 

RTS ; bytes of parameters 

.ELSE 

.IF %1 = 4 

MOVE.L (A7)+, (A7) ; 4 bytes of f^rameters 
RTS 
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put return addr into AO 
remove params from stack 
return to caller 



.ELSE 




HOVE.L 


(A7)^A0 


AOO.V 


«1,A7 


JtP 


(AO) 


.ENOC 




.ENDC 




.IF DEBUGF 


.ASCII XI 




.ENDC 




ENDh 





The following example demonstrates the use of the 
TAIL macro for the purpose of debugging. The example 
assumes that you want to build a stack frame based 
on A6. In a real assembly language procedure the 
zeroes below would be replaced by the local size and 
parameter size. 



-PROC 


SIMPLE 




LINK 


A6,#0 


; zero bytes of locals 


NOP 




; body of procedure 


TAIL 


0, 'SIMPLE • 


; zero bytes of parameters 


-END 







These two macros, HEAD and TAIL, can be used to make it easier to debug 
assembly language routines called from Pascal programs. 

Upon entry to the assembly routine, the stack is as shown in Figure 6-5. 
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Callere Stack Frame 



Callen Dynamic Link 



Fifictlon Result 0f a function) 



Procedure Arguments (if any) 



Static Link (if any) 



Return /Addren 



Dynamic Link (old A6) 



Local Frame 



Dynamic Stack Area 



hBgh Memory 



LOW Memory 



Figinre 6-5 
The Pascal Run-Time Stack 

The funcUon lesult is present only if the Pascal declaration is for a function. 
It is either one or two words. If the result fits in a single byte (a boolean, 
for example), the most significant half (the lower-addressed half) gets the 
result value. 

Procedure ar^Mnents are present only if parameters are passed from Pascal. 
They are pushed on the stack In the orcter of declaration. All reference 
parameters (parameters declared as VAR's in the Pascal Procechjre or Fi^iction 
declaration) are represented as 32-bit acWresses, Value parameters less than 
16 bits long always occi43y a full word. A boolean parameter passed by value 
occupies a word with the value in the most significant byte (the 
lower-addressed byte). All non-set value parameters larger thai 4 bytes are 
passed by reference. 

The static lir^ is present only if the external procedure's level of (teclaration 
is not global. The link is a a-byte pointer to the enclosing static scope. 

It is the responsibility of the assembly language procedure to deallocate the 
return address, the static link (if any), and the paraneters (if any). The ^ 
(stack pointer) must point to the function result or to the previous top of 
stack upon retura Registers D4 through D7 and A3 through A7 must be 
preserved. We recommend that you also preserve D3 and A2. 

6.6J? Register Oonventions 

The following are the register conventions used in the Lisa system. It is your 
responsibility to preserve these registers. 
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D0-D2/A0-A1: Scratch registers (can be clobbered) 

D3,A2: Scratch registers, but should be preserved 

DA-D7/A3,A4: Used for code optimization (must be preserved) 

A5: Pointer to user global s (must be preserved) 

A6: Pointer to base of stack (must be preserved) 

SP: Top of stack 

Registers D3 and A2 may be used at some time in the future by the Compiler 
for code optimization, so you should preserve them also. 

6.6.3 Parameter Passing Between Pascal and Assembly Language 

Parameters are passed between Pascal and assembly language routines in the 
following ways: 



by value: 



boolean 



integer 
longint 
data structure 



a word on the stack with the boolean value in the 

most significant byte of the word (lower, or even 

address). 

a word 

two words 

by address (4 bytes). It is the responsibility of the 

assembly language routine to interpret the data 

structure correctly. 

Xiy reference (VAR parameters> 

all types by address (4 bytes on the stack) 

6.7 Assembly Language Examples 
6.7.1 Using .REF and JDEF Directives 

The first example illustrates the use of .REF and .DEF. These two directives 
allow an assembly language routine to reference other assembly routines. 

The Pascal host file is: 

program WasteTime; 

procedure Halt (time : integer); 

externals- 
begin 

writeln ('Going to waste some time'); 

wait (50); 

writeln ('Fini^ied wasting time'); 
end. 



The assembly language file Is: 

wait 
cycle 



.proc 
.ref 



.ref 
move.l 



inore_time 

(87)+, 80 



need to use a piece of code 
whose entry point is cycle 
defined outside procedure wait 
another outside procedure 
return address in aO 
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mov/e.w (a7)*^d0 ; need to wait this many cycles 

; a parameter for cycle 
Jsr cycle 

jsr mDre_timB ; teste more time 

jrap (aO) ; return 

the subroutine used by wait is defined in the 
following code, this proc could do other things 
besides the cycle routine 

proc def_cycle 

def cycle ; cycle visible to other procs 

code can go here 

nop ; exanple of a line of code 

cycle ; beginning of the cycle routine 

; parameter is in dO 
sub »l,dO 
bne cycle 
rts 

; more code can go here 

.proc more_time ; ipaste more time 

clr dO ; use dO as timer 

ai add *2^d0 

bne ai 
rts 

.end 

6.7.2 String Parameters 

The following program illustrates how to pass a Pascal string to an assembly 
language program, modify the string, and return it Pascal strings have their 
length stored as the first byte in the string. 

NOTE 

Assembly language routines are in read only segments and do not have 
their own data (read/write) area All read/write data should be 
declared in Pascal and passed to the assembly routines using pointers. 
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The Pascal source file is: 

program pasStr; 

type strType = string[80]; 

var str : strType; 
ch : char; 

procedure AsmStr (var str : strType); 
external; 

begin 

str := 'initial string in Pascal main program'; 

witeln (str); 

AsmStr (str); 

witeln (str); 

witeln; 

write ('press any key to continue'); 

read (ch); 
end. 

The assembly language file is: 



.proc 
mov/e.l 
move.l 
move.l 

lea 

clr.l 

move.b 

move.b 
copy subq 
bio 
move.b 
bra 

done move.l 

size .byte 
myStr 

.align 



AsmStr 
(A7)*,A0 
(A7)+,A1 
A2, -(A7) 

size,A2 

DO 

(A2),D0 

(A2)*,(A1)- 

#1,00 

done 

(A2)^(A1)^ 

copy 

(A7)*>A2 
(AO) 

38 

.ascii 

2 



; return address saved in AO 
; address of string from Pascal 
;save scratch register A2 



; get size of string 

;copy size of string 
;done copying string? 
;yes, return to Pascal 
;one char of string 



; restore scratch register 
; return to Pascal 



'this string is from the Lisa Assembler' 
;get on a word boundary 



6-7.3 Writing a Function 

The following example shows how to write a function in assembly language. 
This function returns a boolean value. 
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The Pascal program is: 

program txx)leanFunctlon; 

var int : integer; 
ch : char; 

function swapBytes (var int ; integer) : ixmlean; 
extemal; 

{ if a parameter is passed by reference 
(a var parameter) its addesss is passed 
to the asseirbly routine on the stack } 

begin 
int := 256; 

writeln ('the initial value of int = \ int:l); 
repeat 
if s»ap6ytes(int) then 

writeln ('int = ', int:l) 
else writeln ('int = 0, function value is false '); 
int := int - 1; 
until (int < 0); 

write ('press any key to continue '); 
read (ch); 
end. 

The assembly language function is: 



.func 

move.l 
move.l 

move 

ror 

move 



snapBytes 

(A7)+,A0 
(A7)*,A1 

(A1),D0 

«8^D0 

D0,(A1) 



bne 31 
clr (A7) 
bra 92 



ai 
92 



move 
,end 



#$FFFF, (A7) 
(AO) 



; pop return address 

; get address of mrd to swap 

;. get the number 
; swap the bytes 
; put it back 

; number = so return false (0) 

; return result true (non zero) 
; return to calling program 
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6.7 A Calling Pascal lA) Routines 

The following example illustrates how to call Pascal routines from assembly 
language to do I/O. Note the use of macros for calling the Pascal routines. 

program AsmlO; 

type strType = string [80]; 

var str:strType; 
fl,f2: text; 
ch: char; 

procedure main; 
external; 

{THE FOLLOWNG FUNCnONS ARE CALLED FROM THE ASSEMBLY LANGUAGE 
PROGRAM MAIN TO PERFORM 1/0} 

function f rewrite (f_num: integer; f_namB: strType): integer; 
begin 
case fnum of 
1: rewrite (fl^fname); 
2: rewrite (f2,f_name); 
end; 

f rewrite := ioresult; 
end; 

function f reset (f_nura: integer; fnarae: strType): integer; 
begin 
case f nura of 
1: reset (fl^fnarae); 
2: reset (f2,f_namB); 
end; 

f reset := ioresult; 
erel; 

procedure writeLine (f_num: integer; var S: strType); 
begin 
case f _num of 

0: write (s); {file id = means write tp -console} 

1: write (fl^s); 

2: write (f 2, s); 

enci; 
end; 

procedure writeLF (fnum: integer; var S: strType); 
begin 
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ease f_num of 

0: witeln (s); 

1: writeln (fl,s); 

2: witeln (f2,s); 
end; 
eixl; 

prcxjedure f_close (fjium: integer; lock_file: boolean); 
tJegin 
case f num of 
1: if lock_file then 
close (f 1, lock) 
else 
close(f 1); 
2: if lock_file then close(f2, lock) 
else close(f2); 
end; 
end; 

{THE MAIN PROGRAM CALLS THE ASSEMBLY LANGUAGE MAIN) 

begin 

writeln ("test program - using assembly main routine to do I/O'); 

writeln; 

main; 

write ('press any key to continue'); 

read (input, ch); 
end. 

The assembly language file is: 

.proc main 



; EXTERNAL REFERENCES AND CONSTANTS 





.ref 


writeLF 




.ref 


•rit^ ine 




.ref 


f rewrite 




.ref 


fjreset 




.ref 


fjDlose 


first file 


.equ 


1 


printerld 


.equ 


2 



; id # of file one 

; id # of file '-printer' 

return address to the Pascal main routine Is left on the stack 
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hACROS TO CALL PASCAL FUNCHONS 




.macro 


open write file 


; *i 


— file # 




; *2 


— file name 




clr 


-(a?) 


; reserve space for function 
; result from f_rewrite 


move 


«l.-(a7) 


; file id # as first param 


lea 


%2^a0 


; second param is file name 


move.l 


a0,-(a7) 




jsr 


f rewrite 




move 


(a7)*,a0 


; pop lOresult 


ble 


ai 




error 


XI 


; lOresult > -> error 
; (nested macro call) 


a .endm 






.macro 


open read file 




; «1 


— file # 




; *2 


— file name 




clr 


-(87) 


; reserve space for function 
; result of f __reset 


move 


ni,-(a7) 




lea 


%2,a0 




move.l 


ao, -(87) 




Jsr 


f reset 




move 


(a7)+.a0 


; pop lOresult 


bie 


ai 




error 


XI 


; lOresult > -> error 


tl .endm 






.macro 


write file 


; write a line (with no linefeed] 


; «1 


— file # 




; *2 


— Idbel of string to be written 


move 


«t-(a7) 




lea 


%2^al 




move.l 


al.-(a7) 


; push string address onto stack 


jsr 


writ^ine 


; write it out 


.endm 






.macro 


write! n file 


; write a line of text with 



; linefeed 
*l — file # 
XI — label of string to be written 
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move 


ni, -(a?) 




lea 


t2,al 




move.l 


al,-(a7) 


; push string address onto stack 


Jsr 


writeLF 


; write it out 


.endn 







macro close_file 
\\ — file # 
XI — close status code 

- $00f f normal close 

$0100 - $ffff lock 
move #*l^-(a7) 
move «2^-(a7) 
jsr f_close 

.endm 



.macro error 

; \1 — file name 

write file 0,errStr 



•riteLn_file 0,%1 

rts 

.endm 



write error message 
to -console 
(file id # 0) 
output file name also 
quit 



HAIN ASSEhBLY LANGUAGE PROGRAM 



open_wite_f ile f irst_f ile^ f ilel 
open_irrite_file printerlct printer 



iariteLn_file 

inriteLn_file 

iriteLn_file 

close_f ile 
ciose~fiie 



o^openstr 

f irst_f ile^ string 

printerld, strl 

first_f ile. $0100 
printerld, 



open_read_f ile 1. f ilel 
close_file l.$ffff 

open_read_flle 2.errFile 



; open IG/record-text 



; write the openstr 

; to -console (file # 0) 

; write string to 

; f irst_f ile 

; write strl to printer 

; lock first_f ile 

; do not lock the printer 

; no error should occur 
; preserve filel 

; no errFile around, should 
; cause error. 
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rts 



; back to Pascal main 
; program 



CONSTANTS 



filel .byte 14 

, ascii 'lO/record.text' 

.align 2 

printer .byte 8 

.ascii '-printer* 

.align 2 

string .byte 36 

.ascii 'this string is from the Lisa Assenbler* 

.align 2 ; make sure on even memory 



strl 
myStr 


.byte 

.ascii 

.align 


34 

'another string from Lisa Assenbler' 

2 


openstr 


.byte 

.ascii 

.align 


26 

'opened file lO/record.text' 

2 


errstr 


III 


22 

'error in niwning file ' 

2 


errFile 


III 


6 

'noFile' 

2 



.end 
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6J3 Using Pascal Data Areas 

Assembly language routines are in read only segments and do not have a data 
area. Any data area that must be written into must be declared in the Pascal 
program and referenced in the assembly language program by pointen. The 
following two exanples illustrate the correct and incorrect ways of doing this. 
The correct example illustrates how to do a READLN from an assembly 
language program. 

The first example illustrates the "obvious" and iru^orrect way of doing a 
READLN from an assembly language prc^ram. The Pascal program is as 
follows: 

program AShDemo; 

{ BAD EXATflE: Note that this example does not mrk, because 
it tries to write into a memory space reserved by the 
Assembler. Data space must be set up in the Pascal program 
and referenbed by a pointer variable. TTie following example 
Illustrates the correct way of doing this. } 

type 

PasStr = string[255]; 
var 

ch: char; 

procedure w_i»rite(S: PasStr); 
begin 

write(s); 
end; 

procedure •_iiriteln; 
begin 

writeln; 
end; 

procedure ii_readln(var s: PasStr); 
{ read a line from -CONSOLE and put it into 

(write to) string s } 
begin 

readln(s); 
end; 

procedure main; external; 

begin {ASM)emo} 
main; { call to assembly language routine } 
write('That"s all folks^ type space to continue'); 
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repeat read(ch); until ch = ' '; 
end. {ASHDemo} 

This is the corresponding incorrect assembly leriguage program: 
.pToc main 

.ref i»_wite, ip_witeln, mreadln 

a write 



macro 

lea 

move.l 
jsr 
endm 

macro 

jsr 
endm 

macro 



lea 

move.l 

jsr 

.endm 



X\, aO 
aO, -(a7) 
M write 



a_i«'iteln 
i»_inrlteln 

a readln 



; (s: passtr) 

; *1 = string label 



; no parameters 



; (var s: passtr) 
; *1 = string label 



; Put the address of the string into 
; Dhlch a line is to be read on the 
; stack and call Pascal routine to 
; read the string. 



%1, aO 

aO, -(a7) 
H readln 



; This space has been 
; reserved for the string. 



; MAIN ASSEMBLY LANGUAGE PROGRAM 



awite stringl 

ajiriteln 

a write hello 



; "mis will write a string 
; and a newline. 
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ajreadln stringspace 



NOTE: this Hill fail 
with a bus error 
because stringspace is 
in program space (read 
only), not in read/write 
Hiemory space. 



hello 



a_writeln 
rts 


stringspace 




.byte 

.ascil 

.align 


13 

'Type a line: 

2 


• 


.block 


256 


; Save some space for a 
; readln. This block of 
; meniory is in program 
; space, therefor it is 
; read only. 



Stringl 



.align 

.byte 

.ascii 

.align 

.end 



39 

'TTils string is from the Lisa Assembler.' 

2 



This is the correct ^fay of doing a READLN from an asserrtoly language 
program. Note that the string "s", declared in the Pascal program, is used in 
the w_readln function and passed to the assembly language progrann by 
pointer. 

program ASnOemo; 

{ GOOD EXATFLE: ITiis example does a readln by using a pointer 
variable as a parameter. This allows the string to be 
reserved by the Pascal Compiler. } 

type 

PasStr = string[255]; 
ByteP = "PasStr; 



var 

s: PasStr; 



{ this string is allocated in re^/write 
memory by the Pascal Confiiler } 
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ch: char; 

procedure •_wite(S: PasStr); 
begin 

•rite(s); 
end; 

procedure •_i»riteln; 
tegin 

witeln; 
end; 

function i»_readln: ByteP; 
{ This fmction reads a line into the string s (space 

allocated by the Pascal Oompiler in read/write nemory 

segment) and returns address of s to asseRt}ly routine } 
begin 

readln(s); 

i»_readln := pointer (as); 
end; 

procedure main; external; 

begin {ASHDemo} 
main; { call to assenbly language routine } 
writeCThafs all folks, type space to continue'); 
repeat read(ch); until ch = ' '; 

end. {ftSHDemo} 

This is the correct assembly language program: 
.proc main 

.ref »_wite, i»_«iriteln^ w_readln 



.macro 

lea 
move.l 
jsr 
.endm 


a_wite 

\\, aO 
aa -(a7) 
«i_i»rite 


; (s: passtr) 

; W = string label 


.macro 


ajwiteln 


; no parameters 


jsr 
.endm 


iiL_Kriteln 
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.macro a readln 



; function w_readln: ByteP; 





; This function expects the Pascal routine 
; « readln to return the pointer to the 
; string in nhich a line has been read 




clr.l -(a7) 
jsr « readln 
.endm 






a write stringl 
a_witeln 
a write hello 
a reartln 

jsr ii_wite 

a writeln 
rts 


; this will write a string 
; and a newline 

; leaves the address of 
; string read at top of 
; stack 

; takes top of st.ack as 
; parameter 


hello 


-byte 13 

.ascii 'Type a line: 

.align 2 


< 


Stringl 

-ascii 

align 


.byte 39 

'This string is from the Lisa Assentoler . * 

2 



.end 
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7.1 The Linker 7-1 

The Linker is a program that comdines object files to create an 
execut^le file. 

7.2 Using the Linker 7-2 

The Linker combines object files to produce executable programs. 
Inputs to the Linker are object files^ command files^ or options. 

73 The Linker Options 7-2 

The Linker options control how a link is performed. A list of the 
current option settings is displayed when you enter a "?** to the options 
prompt. 

7.4 How Do I Link a Main Program? 7-4 

A main program is linked by giving the Linker the object file from a 
Pascal program, along with all assembly language routines, compiled 
units^ and libraries that the program uses. 

7S Regular and Intrinsic Units , 7-4 

Regular and intrinsic units are both Pascal units, separately compiled. 
A leguJar unit is linked with a main program and becomes part of the 
executable file. An IntrJnsic mil is shared anong all programs that 
use it, both on disk and in memory. 

7.6 The Linker Listing ....7-5 

The Linker listing provides a summary of the linking process and 
resources used. Optionally, you can request lists of all symbols used, 

7.7 Resolving External Names .7-6 

External names ^x^ symbolic references to separately compiled modules. 
The Linker maps them to actual addresses. 

7.8 Module Inclusion 7-6 

The Linker only includes modules that are actually referenced. 

7.9 Segmentation ..7-7 

Seg^r^nU/yo. program allows portions of it to be swspaed out of 
memory when not in use. Segmentation is controlled by a combination 
of connpiler corrvnands. Linker options, and the ChangeSeg utility. 
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7.1 The Linker 

The Linker combines object files. Its input consists of commands and object 
files. Its output consists of object flles^ link-map Infomiatlon, anxS error 
messages. The output of the Pascal compiler must be linked with 
IOSPASLIB.CIBJ before it can be executed. Otlier object files. Including 
Intrinsic unit libraries, and object files produced by the Assembler, can also be 
linked Into the output daject file. 

When a program is compiled into ai object file, it contains the following sorts 
of things: 

• Object code, in the form of relocatable mainline language, that expresses 
the algorithm of the program. 

• Symbolic (named) references to all locations that were not known at 
compile time. These include externally compiled routines (units and 
Intrinsic units) and the Pascal library support routines (I0SPASL1B.C)BJX 

• Other Information to be used by the Linker. 

The purpose of the Linker Is to resolve all the symbolic references (link 
references to definitions), and output an ob^t file that can be executed. The 
Linker also sorts the code modules Into naned segments. These segments are 
swapped into memory at run time by the Operating System. 

The Linker does its work In two phases. In the first phase, it reads all the 
Ir^t files, aid finds all symbolic references and their corresponding 
definitions. Errors such as duplicate and missing references are detected 
during phase one. In the second phase, the Linker copies code from the input 
files into the output files in executable format 

If the Linker can't find something that is sKidressed symbolically, this is ai 
enor. An enor message will be printed. Indicating the missing module. This 
process of finding the real addresses that correspoind to the symbolic addresses 
Is called /Bsa/u/ng the external referefK^es. 

The Linker expects to find the file INTRINSICLIB. INTRINSICLIB Is a 
directory of libraries and intrinsic units, and includes information for the use 
of the Linker. INTRINSICLIB defines all the Intrinsic units supplied with the 
Workshop system. 

To create an executable file, the Linker must have the following Inputs: 

• The object file from a main Pascal program. 

• IOSPASLIB.CBJ to provide the stareJard Pascal procedures and functions. 
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• IOSFPLIB.CBJ. If you are using any floating point variables. 

• Object files for any other external procedures referenced by the main 
program. These can be Pascal units, assembly language routines, or 
intrinsic units defined in INTRINSIC.LIB. 

The Linker combines these files and creates ai executable object file. If it is 
unable to link these files correctly to create a le0timate output file, the 
Linker displays an error message. If there is an error, the object file is not 
produced. 

When linking a main program, all references to external objects must be 
resolved. Partial links are not supported. 

While it is linking a main program, the Linker does a d&acf C(Xl& analysis and 
does not include any routines that are not referenced. Unnecessary routines 
are eliminated from the main program, and from the regular units given as 
inputs to the link. 

7.2 Using the Linker 

The Linker is started by pressing L in response to the Workshop command 
pronpt The Linker prompts you for the input files, the listing file, and the 
output file. Options can be entered after entering "?" in response to the input 
file prompt After all file names and options are entered, the link begins. 
Hence the set of options in effect is the same throughout the link. It is not 
possible to change cations part way through the link. When entering an input 
file name, it is not necessary to enter the .OBJ extension; the Linker will 
provide that as needed for input files. 

The Linker will accept option commands and input file names from a 
command file. A command file is a text file containing the file names and 
options, one per line, if a blank line exists in the file, the Linker treats this 
as the [RETURN] that signals the end of the Input files. You use a command 
file by typing "<" followed by the name of the text file the commands are in. 
It is not necessary to enter the .TEXT extension; the Linker will provide that 
as needed for all input command files. Create the text file by using the 
Editor. 

The default listing is -console. You can send the listing to a text file by 
entering its name in response to the listing file prompt When sending the 
listing to a text file, you do not need to provide the .TEXT extension, since 
the Linker provides it 

After entering the ouput file name, the link begins. If no errors occur during 
the link and all external references are resolved, the output file is executable, 
A message is printed at the end of the link to tell you if the output is 
executable. 

73 T?ie Linker Options 

To enter the Linker options nnode, type "? [RETURNJ* in response to the 
prompt for srt ir^t file. To leave oJDtions mode and return to entering input 
files, press [RETURN] in response to the options prompt The order in which 
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options are entered is unimportant, because they have no effect until the link 
begins. The last value entered for an option is the value used when the link 
is performed. 

Options are represented by a single character. A "+'* in front of the character 
makes that option take effect. A "-" sets the Linker so that option will not 
happen. In addition to being set on or off, some options have additional 
parameters. Numeric parameters can be in either decimal or hexadecimal. 
Hexadecimal numbers are indicated with a leading "$". The cunent setting 
of all options can be displayed by entering a "?" in response to the request 
for an input file or an option. 

The Linker options are as follows: 

+A Alphabetical listing of symbols. The default is -A. 

+D Debug information. The default is -D. 

-H num -H sets the initial disk space allocated to the program's stack. 
The default is to automatically include space for the program 
variables and the value specified in the +S option. 

+L Location ordered listing of symbols. The default is -L. The 

location is the segment name plus offset. 

+M fromName toName 

+M maps all occurrences of the segment fromName to the 
segment toName. This allows you to map several small segments 
into a single larger segment You can thereby postpone 
segmentation decisions until link time by using many segment 
names in the source code. 

NOTE 

Because options have an effect only when the link begins, it is not 
possible to m^ a segment nane to several different names using this 
option. Also, you cannot use this option to map segments to or from 
the blank segnWit 

+S num +S sets the starting dynamic stacksize to 'num'. The default is 
10000. 

+T num +T sets the maximum allowed location of the top of the stack to 
'num'. The default is 128K. 

* W ♦ W tells the Linker to get intrinsic unit information from a file 
other than INTRINSIC.LIB. 

? Prints the options available and their current values. 
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7.4 How Do I Link a Main Program? 

A main program consists of a Pascal program linked with all routines 
necessary for it to rua A main program is the only type of executable object 
file produced by the Linker. To link a main program you must have the 
following: 

• A compiled Pascal PRCGRAM object file. 

• Object files for any other units the program uses. This includes files for 
regular units and assembly language routines. Any intrinsic units used 
must be defined in INTRINSICLIB. 

• IOSPASLIB.OBJ, and ICBFPLIB.OBJ (if any real variables are usedX 
When you have all the ^X)ve files, proceed as follows: 

1. Execute the Linker by pressing "L" when the Workshop command prompt is 
displayed. The Linker displays a header and asks you for an input file. 

2. Enter aiy desired options. To enter the options mode^ press "? [RETLff^Nj' 
in response to the request for an input file. See Section 7.3 in this 
chapter for information on Linker ojDtions. Press [RETURN] after each 
option entered. When you have entered all the options, press [RETURN] to 
b6gin entering input file names. 

3. Enter the file names for all the object files, pressing [RETURN] after esch 
one. The file names can be entered in any order. You do not need to 
enter the .CBJ extension; the Linker will automatically append it 

4. Press [RETURN] to indicate the end of the input files. 

5. The Linker prompts you for a listing file. Enter the file name desired, or 
press [RETURN] to ajcept the default of displaying the listing on the 
-console. 

6. The Linker prompts you for the output file. Enter the name of the 
executable file you want produced. You do not need to enter the .CBJ 
extension; it is supplied automatically. 

The linking process begins when you press [RETURN] after entering the output 
file name. If the link is successful, the message "Output is executable" will be 
displayed. If the link is not successful, error messages are displayed. 

73 Regular and Intrinsic Units 

The two types of units are regular units and intrinsic units. Each is a 
separately compiled code module that may be used by a main program or 
another unit The syntax of a Pascal unit is explained in the Pascal 
Reference Manual for the Lisa 

A regular unit is combined with a main program by the Linker and included in 
the resulting object file. An intrinsic unit, on the other hand, is stored 
s^3arately on the disk, and loaded at run time. Thus, only one copy of an 
intrinsic mit is kept on the disk, no matter how many main programs use it 
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In addition to being shared on the disk, an intrinsic unit is also shared in 
memory. 
NDTTE 

The current implementation has no provision for users to create new 
intrinsic units. All intrinsic units are supplied by Apple Conputer. 

7S.1 How Do 1 Link with a Regular Unit? 

A regular unit is a separately compiled segment of code. It is written in 
Pascal, and compiled like a regular program. See the Pascal ReferefK^e 
M&TuaJ for the Lisa for information on how to write a mit. See Chapter 5 
in this manual for information on compiling the unit. 

After you have created a unit, the routines in it csn be accessed from any 
other program or regular unit you write. The Linker combines a main program 
with all units it uses. The result is an execut^le object file containir^ all 
the needed routines. 

To use regular units with a main program, follow the procedure in Section 7.4. 
As input, you must give the Linker: 

• The object file of the main program. 

• The object files of all tnits used by the main program. 

• IOSPASLIB.0BJ, and IC6FPL1B.0BJ (if any floating point variables are used). 

The Linker combines all these object files into an executable object file. It 
also does a dead code analysis to eliminate any routines that are not used, to 
reduce the size of the object file. 

7.6 TT« Unker Listing 

A listing is produced each time a program is linked. This listing can be sent 
to a file, or displayed on the console (the default). The +A option gives you 
an alph^Detical list of the symbols QDrocedure names) used in the lirt<. The +L 
option gives yew a list of the names in order of their locaticMi. The listing is 
produced in stages, as follows: 

1. The input files are read, aid a summary of the resources used is printed. 

2. The linking process begins. Information about the size of each segnent is 
printed. 

Errors are reported as they are found, and you are told whether or not the 
output is executable. 

If you requested optional listings, they are also printed. An exatfiple of a 
Linker listing with no options requested is shown in Figure 7-1. Linker 
listings are mainly used for debugging at the machine cocte level. See 
Chapter 8 for more information on the Debugger. 
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Beginnln? leiory - 262489 

After $t»tlc illoc»tion, »e»or« - 186815 

Input file C.OBJ] ? TRANSVOL 

Input file C.OBJ] ? lOSPASLIB 

Input file C.OBJ] ? 

Listing file CCONSOLEiI/C.TEXT] - 

Output file C.OBJJ - TRANSFER_FLS 

Rending filei TRANSVOL.OBJ 

Rending filei lOSPASLlB.OBJ 

Read 2 file*, i»x ■ IBB 

4 segients, lax ' 128 
16 aodules, mx • 1458 
32 entries, MX ■ 2888 
38 ref. lists, lax • 8683 
124 references, lax • 16888 
Linking Main Progra*. 
Active! 4 of 16 read. 
Visible: 1 of 32 read. 
Global data I $886670 
Coiaon data I (886888 

Linking segient K: 8 i file <JT> segi 1 ttzei 2988 
Beginning leiory - 184487 
Ending leiory - 184832 
B Errors detected. 

The output Is executable. 

Elapsed tltli 298 and 384/1888 seconds. 

That's all Folks !!!... 

Figure 7-1 
A Linker Listing 

7.7 Resolving External Names 

An external name is a symbolic entry point into an object module. All such 
names are visible at all times—tfBre is no notion of the nesting level of an 
external name. External names can be either global or local. A /oca/ neme 
begins with a $ followed by 1 to 7 digits. Local names are generated by the 
Pascal conpiler. A global name is any name that is not a local name. 

The scope of a global neme is the entire program being linked. Unsatisfied 
references to global names are not allowed. Only one ctefinition of a given 
global name can occur in a given link. The one exception to this is that the 
Linker accepts duplicate names wf^re one instance is in a main program or 
regular unit^ and the other is in an intrinsic library file. In this case^ a 
warning is issued, and the entry in the main program or regjlar unit is used. 

The scope of the local name is limited to the file in which it resides. All 
references to a given local name must occur within the same input file. 
When a link is done, global names are passed through to the outJDut file 
unmodified, but local names are renamed so that no conflicts occur between 
local names defined in different files. 

7.8 Module Inclusion 

When linking an intrinsic unit, all cc^e mcwjules in the unit are included. 
When linking a main program with regular units, the Linker does a dead code 
analysis ard does not include any modules that are not called. 
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7.9 Segmentation 

Segmenting a progrstfn makes it possible for portions of the program that are 
not being used to be swapped out to disk^ thus making better use of memory. 
The way a program is segmented affects its performance. 

Segmentation is controlled by three things: 

• The $S Compiler command and the .SEG Assembler option, which assign 
segment names to source code modules. 

• The +M Lirtfcer option, which enables you to remap compiler segment 
names into new segment names. 

• The ChangeSeg utility, which enables changing the segment names prior to 
linking. See Chapter 10 for information on ChangeSeg. 
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ai The Debugger , 8-1 

The Detxigger allows you to examine and modify memory^ set 
breakpoints, assemble and disassemble instaictions, and provides other 
functions for run-time debugging. 

62 Inadvertent Entry Into the Debugger 8-1 

If you have a bug in your program or a system malfunction, you may 
inadvertently enter the Debugger. This section tells you how to deal 
with this. 

8.3 Using the Debugger ,..8-6 

Enter the Debugger by pressing D in response to the command prompt 
or by pressing the NMI key. The Debugger prompt (>) indicates that it 
is ready to accept commands, 

8.4 TTie Debugger Commands 8-10 

Commands are available for assembly and disassembly of instryctions, 
displaying memory and registers, setting breakpoints and traces, merpory 
mstfiagement, &nti base conversions. 

63 Summary of Debugger Commands , 8-20 
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8.1 The Debugger 

The Debugger allows you to examine and modify memory, set breakpoints, 
assemble and disassemble Instructions, and perform other functions for 
run-time debugging. 

Procedure ngffnes are available to the Debugger for program units conpiled 
with the D option on. The Debugger uses the symbolic names wherever 
appropriate. 

The Debugger's symbol table contains the user symbol table and the 
distributed procedure natfT«s. The user symbol t^le contains symbols the user 
defines while using the Debugger and the predefined symbols for registers. 
Section 6.6 in this manual contains more information about the rm-time 
environment of programs. 

When you enter the Debugger, the Debugger screen is made visible by the 
Ctebugger. You can display the main screen by pressing [tPTICN] and [ENTER] 
to see the state of the program before the Debugger was entered. Redisplay 
the Debugger screen (by pressing [OPTION]-[ENTERJ again) to continue with 
debusing. 

8.2 Inadvertent Entry into the Debugger 

Accidental entry into the Debugger can be caused by a bug in the program 
you are running or by some malfunction in the system. A message from the 
Debugger will suggest the type of problem. The messages and the actions you 
can take for program bugs are described in Section 8.2.1 below. System 
malfunctions are described in Section 8.2.2. 

8.2.1 Program Bugs 

You can enter the Debugger while your program is executing for any of the 
following reasons. More informatim on these conditior^ can be found in the 
MC680D0 16 Bit Micwprocessor User's Manual. 

• A value range error 

• An illegal string index 

• A bus error or address error 

• An illegal instnrction or a privilege violation 

• Integer division by zero 

• Spurious interrupt or tffwxpected exception 

• Overflow when TRAPV is executed 
" Line 1111 Emulator 
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• System malfunction 

• Intentionally, by pressing the NMI key. This is the way to temiinate an 
infinite loop (when «-period doesn't stop your program). Do not use NMI 
when riaming system program. 

Usually the system will tell you the most appropriate action to take, for 
example, "type g to continue". Follow these instructions unless you have a 
special reason for doing sonrething different. 

Programming errors are descritjed in Section 8.2.1.1 below. Stopping an 
infinite loop is described in Section 8.2.1.2 below. 

8.2.1.1 Program errors 

If you have an error in your program it will drop into the Debugger and 
display one of the following messages: 

If a range check error occurs in application code, the message displayed is: 

VALUE RANGE ERROR In process gid <gggg> 

value to check = <vvvv> lower bound = <nnnn> upper bound = <uuuu> 

return pc = <pppppp> caller a6 = <cccccc> 

Going to Lisabug, type g to continue. 



or: 



ILLEGAL STRING INDEX in process Of gid <gggg> 

value to check = <vvw> lower bound = <nnnn> upper bound = <uuuu> 

return pc = <pppppp> caller a6 = <cccccc> 

Going to Lis^ug, type g to continue. 

where: 

<gggg> is the global process ID of the process that incurred the 

exception. 
<vvvv> is the value that is outside the range. 

<nnnn> is the lower bound of the range. 

<uuuu> is the upper bound of the range. 

<pppppp> is the acWress of the statement after the call to the range 

check routine in Paslib. 
<cccccc> is the address of the link field at the time of the call to 

Paslib. 

During execution applications can field hardware excqations. Refer to the 
h'KXSOOO 16 Bit Micrcprocessor User's Manual for definitions of these 
hardware exceptions. If such an exception occurs, the system displays one of 
ttie following messages: 
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Bus error or address error exception: 

EXCEPTION in process of gid <gggg> 

Process is about to be terminated. 

access address = <aaaaaaaa> = mnu* <ninm> (segment name)^ offset 

<oooo> 

inst reg = <rrrr> sr = <ssss> pc = <pppppp> 

saved registers at <xxxxxxxx> 

Going to Lisabug, type g to continue 

Any other hardware exception: 

EXCEPTIC^l in process of gid <gggg> 
Process is about to be terminated, 
sr = <ssss> pc = <pppppp> 
saved registers at <xxxxxxxx> 
Going to Lisatxig, type g to continue 

where: 

EXCEPTION is one of : 
BUS ERROR 
ADDRESS ERROR 
ILLEGAL INSTRUCTION 
PRIVILEGE VIOLATION 
SPURIOUS INTERRUPT 
UNEXPECTED EXCEPTION 
ZERO DIVIDE 
CHK RANGE ERROR 
OVERFLOW 
LINE illl EMULATOR 

<gggg> is the global ID of the process that incurred the exception. 

<aaaaaaaa> is the address that caused the bus or address error 
<mmm> is the segment number represented by <aaaaaaaa> and 

<oooo> is the offset within that segment 

<rrrr> is the value of the instruction register at the time of the 

exception 
<ssss> is the value of the status register at the time of the 

exception 
<pppppp> is the value of the program counter at the time of the 

exception 
<xxxxxxxx> is the address of the saved register information 

All numben displayed are ctecimal; the segment name is displayed only if the 
secpDent runrixx makes sense to the Operating System. 

If the exception is divide by zero, overflow, or CHK out of bounds, the 
process is not terminated SBid the line to that effect is not showa If the 
process has declared an exception handler for this exception, control passes to 
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the handler after you type g to LisaBug, and the process then continues 
execution. If no handler has been declared, the system default handler 
terminates the process. If the exception is a bus error and the segment name 
is 'stack seg', a stack overflow has probably occurred. To find your bug you 
can do a SC (stack crawl) and IL (immediate disassemble) to find where you 
are in the program. The instruction register tells you the exact instruction 
being executed. The PC might be 2 to 10 bytes ahead. 

You can declare an exception handler in your program to handle divide by 
zero, overflow, or CHK out of bounds exceptions. Then your process will not 
be terminated by the system if this type of exception occurs. You can also 
declare an exception handler for the "SYS_TERMINATE" exception in your 
program. This exception handler will then get executed if your process has a 
fatal error as described above. This allows you to clean up your program, 
close your files, etc. (in this exception handler) before your program is 
terminated. See the Operating System RefererKe Manual for the Lisa for 
how to declare an exception handler. 

8.Z1J2 Terminating an Infinite Loop 

NOTE 

The following procedure should be used on user programs only. To 
terminate a systems program use «-period. 

If your program is in an infinite loop, or appears to be doing nothing, you can 
enter the Debugger by pressing the NMI key (the - key on the numeric 
keypad). This will put you into the Debugger and show the trace display, 
which looks something like: 

Level 7 Interrupt 

aaaaaaaa bbbb <instr> 

PC=xxxxxxxx SR-xxxxxxxx US=xxxxxxxx SS=xxxxxxxx DO=d PROC=yyy 
O0=xxxxxxxx Dl=xxxxxxxx D2=xxxxxxxx 03=xxxxxxxx 
OA=xxxxxxxx 05=xxxxxxxx D6=xxxxxxxx D7=xxxxxxxx 
AO=xxxxxxxx Al=xxxxxxxx A2=xxxxxxxx A3=xxxxxxxx 
A4=xxxxxxxx A5=xxxxxxxx A6=xxxxxxxx A7=xxxxxxxx 
> 

where: 

aaaaaaaa is the current acklress 

bbbb is the contents of the current address 

<instr> is the current instruction disassembled 

xxxxxxxx is the contents of the specified register 

d is the current domain (0 - 3) 

yyy is the process ID of the interrupted process 

This information is used in debugging your program. If your program is in an 
infinite loop, proceed as follows: 
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1. Check the domain (CXJ-d). If the domain is zero^ you are cunently 
executing in system code. You must be executing user code before you 
can work on your program (domain 1-3). See Section 8.2.1.3 "User Break" 
below for a procedure to get you into user code. 

2. Make sure you are in your own process^ insteaj of another process that 
may be running in the background. If the current address does not show 
the nane of one of your procedures, type SC (stack crawl). The procedure 
names displayed should be from your program. 

3. If you are in a ti^t loop you can step the PC beyond it by using other 
Debugger commands. In order to do this you must be familiar with 68000 
assembly language and the Debugger commands. Most often you will just 
want to stop your program. This is explained t)elow. 

4. First m£tf<e sure the domain is not zero. Type "PC 0" and press [RETURN]. 
This will cause an exception wf^n you restart your program. 

5. Type "G" and press [RETURN]. Your prograaTi will restart, cause 2S\ 
exception, and irrtfriediatly drop back into the Debugger with an exception 
message that includes the instructions "Type g to continue". 

6. Type "G" arrcl press [RETURN]. Your program will be terminated. 

8.2.13 User Break 

The user break facility stops processing in user process code. Use this 
procedure if the trace display indicates that the domain is zero. (Either 
DOMAIN-0 or DOMAIN - n OVERRIDDEN TO 0.) The UBR command will set a 
breakpoint at the next instruction to be executed in the user process. To stop 
your JDrogram in user process code, proceed as follows: 

1. Type "UBR" and press [RETURN]. 

2. The system will continue executing until it returns to user process code, 
then it will drop beck into the Debugger. You can now proceed to work 
on your code. 
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^ NOTE 

There are two cases when UBR will not set a breakpoint The first is 
if the system is interrupted while a system process is running (PRCCESS 
= 0^ 1, or 2). The second is if the system is interrupted while the 
scheduler is running and it has not chosen a process to run. If LBR 
ctoes not seem to be working, check for this as follows: 

Type "ID PC-4" and press [RETURN], If the STCP instruction is 
displayed, you are in the scheduler. You must press "G" and return to 
start the system running again and press NMI again. 

If your program is doing a READ or READLN, the system will display 
the STCP instruction. The only way to continue execution is to press 
"G" and enter scwnething from the keyboard to satisfy Vn^ read. 

&2.2 System Malfunctions 

If there is a system malfunction, the system will enter the Debugger with a 
mess^e indicating a system error or an EXCEPTION display with the domain 
zero. The message will include instructions telling you what command to 
type. Ususally it will tell you to type OSQUIT. It may be necessary to type 
this command several times. 

If you are having problems with system malfunctions, call your support hotline 
for more informatioa It will be useful to have copies of the messages that 
were displayed. If you have a printer connected to the lower or upper port, 
use PL or PU to generate a bug report 

a.3 Using the Debugger 

Type D to the command prompt to invoke the Debugger. It asks: 

Debug what OS file? 

Enter the name of the object file you want to debug. It is xixn with a 
breakpoint set at the first instruction and drops you into the Debugger 
immediately. The Debugger command prompt is >. The default radix is 
hexadecimal. 

Another way of getting into the Debugger is by pressing the NMI key, which 
is the "-" key in the top row of the numeric keypad. 

When you get Vne command prompt, the Debugger is ready to accept 
commands that allow you to: 

• Display and set memory locations 
" Set and display registen 

" Assemble and disassemble instructions 

• Set breakpoints, patchpoints, and traces 
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• Manipulate the rrwnory management hardware 

• Set up timing buckets for execution timing 

• Perform utility functions including: 

" Symbol and jase conversion 

• Move the Debugger window 

• Print Debugger Information 

8.3.1 Examples of Using the Detxjgger 

This section gives examples of how to use the Debugger. An expiration of 
all Debugger commands is in Section 8.4. A summary of all Debugger 
commands is in Section 8.5. 

If you type a file name to the prompt from the Debug command, the 
Debugger starts up with the program counter at the start of the program. To 
see one instruction disassembled at 32F96, type: 

>1D 32F% 

ID stands for Immediate Disassemble. Each subsequent ID command, if given 
without any address, disassembles the next instruction found. In addition to 
printing the value of each byte, the Debugger prints the ASCII equivalent of 
that value, if a printable one exists. If none exists, it prints a period. 

To disassemble 20 consecutive addresses, type 

>IL 

IL, Immediate Disassemble Lines can also be followed by an address. 
Subseqtent IL commands disass^nble successive blocks of 20 consecutive 
locations in memory. 

If the object file being examined was compiled with the D+ Compiler option, 
the procectire names are available in the D^3ugger and can be used in any 
expressions. For example, 

>IL Poo 5 
disasserrtjles the first 5 lines of procedure "Foo". 

>BR Foo+40 
sets a breakpoint 40 bytes into procedure "Foo". 
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You can also use labels in immediate assemblies: 

>sy Ken 6000 

>A Ken NCP 
assembles a NCP instaiction at the address "Ken", which in this case is 6000. 

>A 6000 

>Rich: JMP $100 

> [RETURN] 

enters the immediate asserrtoler at 6000, defines the label "Rich", and 
assembles a Jf^ instruction. 

8.3.2 A Pascal Example: Range Errors 

The Debugger can be used for run-time debugging of Pascal programs. Its 
displays and commands reference Pascal procedure names to make it easier to 
debug programs. If your program has a fatal run- time error, it will drop into 
the Debugger and give you a trace display. The trace display will include the 
name of the proceckjre that was executing. 

One common reason for drof^ing into the Debugger is if you get a ran^ error. 
Range errors can be caused by array indexes, string value parameters, ^k1 
assignments to variables of a subrange type. If you get a range error, you 
will drop into the Debugger with the RANGE ERRCR exception message. 

To help find the error in your program, give the Debugger ai IL PC-20 
command. This will give you a display of the previous 20 lines of assembly 
code. You should see sffi instruction of the form: 

CHK #<lim>,<data reg> 

where <lim> is an integer, and <data reg> is a data register pO - Ul\ Lim is 
the allowable value. The coitents of the data register is the actual value 
that was out of range. The contents of all the registers can be displayed with 
the TD (trace display) conrffnand. 

Figure 8-1 shows a Pascal program that produces a check range error. Figure 
8-2 shows the resulting Debugger display, with an explaiation of what the 
display means. 
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program check; 
war ch:char; 

procedure localproc; 
var 

i : integer ; 

a:array[0. .103 o-f 1..7; 
begi n 
i := 9; 
aC3] := i ; 
end; 

begin 

wr i te1n<'pre55 space to run, 

read<ch) ; 

local proc ; 
end. 



'); 



Figure 8-1 
Pascal Program that Produces a Check Range Error 



(D 



CHK Rf=»NGE ERROR in process o-f qid 
sr = PC = 2359339 
saved registers at 13369278 
Going to Lisabug, type g to continue, 



r 



r 



PC MOVE.B D0,$fFF5(A6) 
US=00F7FBEC SS=00CBFEE0 D0=1 Pl»=00019 
D2=000000C0 D3=000264A7 
D6=12CC4EF9 D7=00840000 
A2= 00240060 fl3=00CCA22fl 
A430flO:fi22A A5=00F7FC44 A6=00F7FBFA A7=00F7FBEC 
'> i 1 PC-2C i 

00A4 0024 0000 4A6F EFF2 4E56 FFF2 3D7C ...*.. Jo 
EFF2 LOCALPRO TST.W $EFF2(A7) 
LINK 



Level 7 Interrupt 
LOCALFRO+001A 1D40 FFF5 
PC= 00240022 SR=0000 ^0 

D0=00100009 D1=0000I 

04=00000001 D5MEF90084 
A0=00F8126E A1=00CCA22A 



00240002 

LOCALPRO+0000 4A6F 
LOCALPRO+0004 4E56 FFF2 
LOCALPRO+0008 3D7C 0099 FFFE 
LOCALPRO+000E 302E FFFE 
LOCALPRO+0012 3200 
LOCALPRO+0014 5341 
LOCALPRO+0016 43BC 0096 
LOCALPRO+001A 1D40 FFF5 
LOCALPRO+001E 4E5E 
LOCALPRO+0020 4E75 
>P1 



MOVE.W 
MOVE.W 
MOVE.W 
SUBQ.H 
,CHK 



A6,»JFFF2 

«t0009,*FFFE(A6) 

*FFFE(A6)JD0 

D0,Di jm ^ 

Tt$0006iDl ^^ 




PC /Ty MOVE.B D97$FFF5(A6) 



^-t' UNLK 
RTS 



A6 



Figure 8-2 
Check Range Debugger (Display 
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Notes: 

1. Debugger display produced by check range error. 

2. Actual value in Dl. This is the value that was checked and found out of 
range. 

3. Disassembly command typed in to display the assembly language display of 
the program causing the error. 

4. Look for the CHK instruction near the PC. 

5. Note that the previous identifier is LOCALPRO, therefore the error 
occurred near the beginning of LOCALPRO. 

6. Value in register Dl was supposed to be in range 0..6. 

7. Pascal lower limit (#$1) was subtracted from Dl. Therefore the range in 
the Pascal type was 1..7. 

More Information on the run time environment of a Pascal program Is found in 
Chapter 6. 



8.4 Trie Deixigger Commands 

This section gives the definition of each Debugger command, 
are grouped together according to finctioa 



The commands 



8.4.1 



Definitions 

Constant 

SConstant 

^Constant 

'ASCII String' 

Name 

Expr 



Exprlist 
Register 



RegName 



A constant in the default base. 

A hex constant. 

A decimal constant. 

An ASCII string. 

A symbol in the symbol table. 

An expression. Expressions can contain names, regnames, 

strings, and constants. Legal operators are + - * /. 

Expressions are evaluated left to right. * and / take 

precedence over * and -. ( and ) can be used to indicate 

indirectloa < and > can be used to nest expressions. In those 

cases where an odd value is probably a mistake, the 

Debugger warns you that you are trying to use an odd 

address. If you decide to go ahead, it subtracts one from the 

address given. If the Compiler option D+ was used^ 

procedure names are legal in expressions. 

A list of expressions separated by blanks. 

The name for any of the 68000 registers, as follows: D0.,D7 

are the data registers, A0..A7 are the address registers, the 

program counter PC, the status registers SR, US, or SS. Note 

that A7 is SP (the stack pointer). 

RD0..RD7, RA0..RA7, PC, US, or SS. A predefined symbol in 

the symbol table with a value set by the Debugger. The 

value is equal to the value of tf« register in question. The 

Debugger automatically updates the values of these symbols. 
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The 'R' is appended to distinguish the register names from 
hexadecimal numbers. 

8.4.2 Display and Set Memory Locations 

The following commands display and set memory locations. 

SM exprl exprlist 

Set memory with exprlist starting at exprl. SM assumes that each element of 
exprlist is 32 bits long. To load different length quantities, use SB or SW 
described below. If the expression given is longer than 32 bits, SM takes just 
the upper 32. For example, if we ask the Debugger to; 

SM 1000 'ABCDE' 

it deposits the ASCII equivalent of "ABCD" starting at 1000. 

SB exprl exprlist 

Set memory in bytes with exprlist starting at exprl. 

SW exprl exprlist 

Set memory in words with exprlist starting at exprl. Exprl must be an even 
address, or the address will be rounded down to the nearest even address. 

SL exprl exprlist 

Set memory in long words with exprlist starting at exprl. Exprl must be an 
even address or it will be rounded down to the nearest even address. For 
example, 

SL 100 1 

is equivalent to 

SM 100 0000 0001 

DM expr 

Display memory. Display 16 bytes of memory starting at expr. DM RA3+10, 
for example, displays the contents of memory from 10 bytes beyond the 
address pointed to by A3. DM (110) displays the contents of the memory 
location addressed by the contents of location 110. Expr must be an even 
address or it will be rounded down to the nearest even address. 

DM exprl expr2 

Display memory. If exprl < expr2, then display memory from exprl to expr2. 
Otherwise, display memory for expr2 bytes starting at exprl. 

DB expr 

Display memory as bytes. Expr can be any byte address. 

DW expr 

Display memory as words. Expr rmist be an even address or it will be rounded 
down to the nearest even address, 

DL expr 

Display memory as long words. Expr must be an even address or it will be 
rounded down to the nearest even address. 
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8.4.3 Finding Patterns in Memoiy 
FB expri expr2 exprlist 

Find Byte. Find the byte or bytes "exprlist' in the address range specified. If 
expr 1 < expr2 then search the range from exprl to expr2. Otherwise search 
for expr2 bytes starting at exprl. 

FM exprl expr2 exprlist 

Find Memory. 

FW exprl expi2 exprlist 

Find Word. 

FL exprl expr2 exprlist 

Find Long word. 

8A4 Set and Display Registers 
TD 

Display the Trace Display at the current PC. An example of the trace display 
is shown in Figure 8-3. It shows the instruction executing at the time the 
program was interrupted, the current value of all the registers, and the 
current domain and process. 



Leuel 7 Interrupt 
LOCALPRO+eeiA 1D49 FFF5 



MOVE.B D8,IFFF5(A6) 

us=88F7FBEC ss=e8CBFEEe Do=i p«=ee8ie 



PC=8824e022 SR=8ee8 

D9=013C8089 01=88008888 D2=888888C8 03=88199752 

04=88888001 05=53656758 06=78487^28 07=88800088 

A8=e8F8126E Al=e8CCB614 ft2=80248860 A3=00CCB614 

A4=8eCC75FC A5=80F7FC44 ft6=e8F7FBFA A7=08F7FBEC 



Figure 8-3 
The Trace Display 

register 

Display the current value of the register. DO, for example, is a command to 
the Debugger to display the current value in the register DO. RDO, on the 
other hand, is a name automatically placed in the symbol table to give you a 
handle on the contents of DO in an expression. Thus, to display the current 
value in the DO data register, type the command DO. To display the 
instruction pointed to by the AO address register, type the command ID RAO 
(immediate dissassemble at the address RAO, which is predefined to be the 
contents of the AO register.) 
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register expr 

Set the register to expr. For example, to set register D3 to zero, type D3 0. 

8.45 Assemble and Disassemble Instnjctions 

These comm^xJs are used to display code in assembly language format, and to 
enter code in the form of assembly language statements. 

A expr statement 

Assemble one or more assembly language statements (instructions) starting at 
expr. You can continue assembling instructions into consecutive locations, 
pressing [RETURN] after each statement Press just [RETURN] to exit the 
immediate assembler. Note that the immediate assembler cannot assemble 
any intrinsic unit instructions, but they are correctly disassembled. Code 
segments cai be write protected, which prevents you from assembling 
instructions into them. This can be overridden with the WP command to 
disable write protectioa 

A expr 

If you use the form A expr, the Debu^er prompts you for the statement to be 

assembled. 

ID 

Disassemble one line at the next address. 

ID expr 

Disassemble one line at expr. 

IL 

Disassemble 20 lines at the next address. 

IL expr 

Disassemble 20 lines starting at expr. 

IL exprl expr2 

Disassemble expr2 lines starting at exprl. 

IX statement 

Invnediate execution of a single instruction. The user's PC is not changed by 
this operation. 

8./L6 Set Breakpoints and Traces 

These commands are used to trace program execution. 

BR 

Display tfre breakpoints currently set You can set up to 16 break(X}ints with 
the Debugger. Breakpoints are displayed both as addresses and as symbols. An 
asterisk marks the point of the breakpoint in the disassembly. 



8-13 



workshop user's Guide We Detjugger 



BR exprlist 

Set each breakpoint in exprlist. Symbols are legal of course, so you cart 

BR Ralph+4 
If Ralph is a known symbol. 
Expressions can be of the form: 

ppraaaaa 

where pp Is the process ID^ and aaaaa is the address in that process where 
you waait the breakpoint set. If the process ID is 0, the breakpoint is set in 
system code in domain 0. If no process is given, the current process is 
assumed. The current process is shown in the TD display described above. 

Breakpoints cannot be set on intrinsic unit instructions. 

CL 

Clear all breakpoints. 

CL exprlist 

Clear each breakpoint in exprlist. 

G 

Start running at the current PC. 

G expr 

Starting running at expr. 

T 

Trace one instruction at the current PC. 

T expr 

Trace one instruction at expr. 

SC expr 

Stack Crawl. Display the user call chain, Expr sets the depth of the display. 
It can be omitted. The Stack Crawl display is shown in Figure 8-4. More 
information on the Pascal stack can be found in Section 6.6. 

>sc 

At LOCALPRO+eeiA 

Stack frame at eBFTFBFA called from CHECK+8838 
, Stack -f raffle at 09F7FC44 

Figure 8-4 
Tne Stack Ciawi Display 
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procedure name 

This calls a user procedure or function. It is your responsibility to save and 
restore registers and push any necessary parameters. If you want execution to 
stop upon return, you must set a breakpoint on the current PC. For example: 

BR PC ; set breakpoint on PC. 

IX MOVEM.L D0--A6,-(A7) ; save registers. 

; push params if needed. 
Fm ; call procedure FOCI 

IX MOVF.M.L (A7)+J)0-A6 ; restore registers. 
CL PC ; remove break point. 

A function can be called in a similar manner. Remember to allocate space 
for the function result before pushing any parameters. Use either CLR.W 
-(A7) or CLR.L -{M). 

OSQUIT 

A procedure that might rreed to be called is OSQUIT. It exits from the OS. 
We recommend that you avoid this whenever possible. 

UBR 

UBR is a procedure that sets a breakpoint in the user code so that you will 
drop into the Debugger as soon as you reenter user code. UBR is explained in 
Section 8.2.1.3. 

8A7 Manipulate the Memory Management Hardware 

These commands change the memory management hardware of the Lisa More 
information on the memory managment hardware can be found in the Use 
Hardware Manual 

LP expr 

Convert logical address to physical address. 

DO expr 

Set the SEG1/SEG2 bits. These bits determine the hardware domain number. 
If the Status Register shows that you are in supervisor state, then the 
effective domain is zero, and the domain number returned by the Debugger is 
the domain that would be active if the SR were changed to user state. Note 
that if you change domain, you should restore the original domain before you 
type g. 

WP or 1 

Disable (Q) or Enable (1) Write Protection. The default is 1. 

MM start [endorcounlj 

MM with one or two arguments displays information about the MMU registers. 
The second argument defaults to 1. If the starting address is greater than the 
second argument, the second argument is a count of the number of MMU 
registers to be displayed. If the starting address is less than the second 
argument, the second argument is the last register displayed. 
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MM 70 

displays 

Segment[70] Origin[000] Limit[00] Control[C] 

These values are the Segment Origin^ Limit, and Control bits stored by the 
hardware for each MMU register. As can be seen from a careful perusal of 
the hardware documentation, a Control value of C meais the segment in 
qtestion is unused (invalid^ If the Control value is valid (7, for example), the 
Debugger also displays the Physical Start and Stop addresses of the segment. 

MM 6d00 8 

displays the MHJ register information for the 8 registers starting at register 
64 (decimal 100). 

MM num org llm cntrl [endjorjcount] 

The H^ command followed by four arguments sets the MMU information for 
segment 'num'. The Origin, Limit, and control bits can be changed. 

MM 70 100 f f 7 

sets the Origin of segment 70 to 100 and the control bits to 7 (a regular 
segment). The segment limit of -1 makes the segnent 512 bytes long. 

8A8 Timing Functions 

The Debugger allows you to create up to 10 timing buckets for measuring 
executim times. Using the microsecond timer in Driven, time is accttfmilated 
in each bucket and saved along with a count of the nurrtjer of times the 
bucket was entered. 

Typically, this would be done as follows: 

1. Enter the Debugger and enter the process number that you want to time 
using the BT command. 

2. Create one or more timing buckets with the TB command. 

3. Set a breakpoint to stop execution at some point 

4. Go. 

5. When the breakpoint is reached, print the timing summary with the PT 
ccrrmand. 

6. Use Uie End Timing (ET) command to remove all timing buckets. 
The timing commands are as follows: 

BT oqar 

Begin timing. Expr specifies the process number. If the expr is not given, the 
current process is assumed. A process number of can be used to indicate 
domain 0. 
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TB addrl addr2 

A timing bucket is created from addrl to addr2. 

PT 

Print timing summary. There are five columns printed: 

1. Bucket number 

2. Total time in this bucket 

3. Number of times this bucket was entered. 

4. Starting address for this bucket. 

5. Ending address for this bucket. 

ET 

End timing. This command prints the timing summary and removes all the 

timing buckets. 

KB expr 

Kill Bucket. This can be used to remove a single bucket Expr is the number 
of the bucket to remove. 

RT 

Reset timers. This resets the timing and count tables while leaving the 
bucket definitions intact 

Note that all addresses are in the same process. The process number is 
defined by either the BT command or the first TB^ PT, KB, or RT command. 
If the process number is not given in the BT command, the cunent process is 
assumed. 

8A9 UUlity functions 

The utility functions include: 

• Symbol and base conversion 

• Movir^ the Debugger window 

• Settir^ the NMl key 

• Printing Debugger displays 

• Dumping memory to a diskette 

8A9.1 Symbols and Base Conversion 
SY 

Display the values of all symbols. 

SY name 

Display the value of the symbol name. 

SY name expr 

Assign expr to the symbol name. 
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CV exprlist 

Display the value of each expression in hex and decimal. 

SH 

Set the default radix to hex. 

SO 

Set the default radix to decimal. 

8A9.2 Moving the Detjugger Window 
CS 

The CS command clears the Debugger screen. 

P expr 

Set port number to expr. Valid port numbers are: 

Lisa keyboard and screen (default) 

1 Serial A 

2 Serial B 

If you move the port to a serial port you must have a modem eliminator 
connected to that port. 

RS 

Display the patch Return address Stack 

8A9.3 Setting the NMI Key 
NM 

Displays the key code for the NMI key. 

NM expr 

Sets the NMI key to be key code expr. A value of zero disables the NMI key. 

^ NOTE 

This affects the entire system. If the NMI key is disabled, you cannot 
use it to stop an infinite loop, or a system hang. 

For example: 

>NM $21 

Sets the NMI key to be hex 21, which is the "-" key in the top row of the 
numeric keypad. This is the default NMI key. 

aA9.4 Printing from the Debugger 

The following commands allow you to print information from the Debugger on 
the dot matrix printer. 

PR expr 

The PR command enables or disables printing to the two-port card. When 
printing is envied, all Debugger output to the screen is printed. 
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expr = 1 enable printing upper port 
exJDr - 2 enable printing lower port 
expr = disable printing 

NOTE 

The Debugger only supports printing to a printer connected to the 
lower or upper port. The serial printer is not supported. If the printer 
is not connected the Debugger will hang when you try to print with the 
PL, PU or PS command. 

PS expr 

The PS command prints the entire primary or alternate screen. Printing must 
t« enabled (the PR command) before PS is used. Expr tells which screen to 
print: 

expr - 1 print primary screen 
expr = print alternate screen 

FF 

The FF command sends a form feed to the printer if printing is enabled. 

PL andPU 

The PL SHTd PU commands print a bug report on the lower and upper ports 

respectivly. The bug report consists of the following: 

Dump of the primary screen 

Dump of the alternate screen 

Description of the exception 

Trace Display 

Stack Crawl 

Disassemble of 20 lines from PC-$2Q 

Display words from RA6-$20 for $80 bytes 

8A9.5 Dumping Memory to Diskette 

The following commands allow you to create a copy of the contents of 
memory on a diskette. 

ML andMU 

The ML and MU commands dump a copy of memory to the lower and qpper 
diskette respectivly. This information cai be used to reconstruct the 
conditions at the time of a crash, for example. These commands work as 
follows: 

• If there is a disk in the drive, it is ejected. 

• You are prompted to insert a disk. 

• The disk is formatted aid all necessary information is copied to it This 
process takes about 3 1/2 minutes. 
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8.5 Summary of the Oeixigger 

proceckjre name 

register 

register expr 

A expr statement 

A e>q3r 

BR 

BR exprlist 

BT expr 

CL 

CL expriist 

CV exprlist 

DB expr 

DL expr 

DM exprl expr2 

DO expr 

DR 

DW expr 

ET 

FB exprl expr2 exprlist 

FF 

FL exprl expr2 exprlist 

FM exprl expr2 exprlist 

FW exprl expr2 exprlist 

G 

G expr 

ID 

ID expr 

IL 

IL expr 

IL e>qDrl expr2 

IX statement 

KB expr 

LP expr 

ML 

MM exprl expr2 

h^ nun org lim Ctrl 

MR 

MU 

NM 

KM expr 

OSQUIT 

P expr 

PL 

PR expr 



Commands 

Call the procedure. 

Display the current value of the register. 

Set the register to expr. 

Assemble statement at expr. 

Assemble one statement (instruction) at expr. 

Display the breakpoints currently set. 

Set each break|M)int in exprlist 

Begin timing process expr 

Clear all breakpoints 

Clear each breakpoint in exprlist 

Display the value of each expression in hex and 

decimal. 

Display memory as bytes. 

Display memory as long words. 

Display memory. 

Set the SEG1/SEG2 bits. 

Display index or ranges of dump RAM. 

Display memory as words. 

End Timing; print summary and remove buckets 

Find Byte. 

Send form feed to printer 

Find Long word 

Find Memory 

Find Word 

Start running at the current PC 

Starting running at expr 

Disassemble one lire at the next address 

Disassemble one line at expr 

Disassemble 20 lines at the next address 

Disassemble 20 lines starting at expr 

Disassemble expr2 lines starting at exprl 

Immediate execution of one instruction 

Kill Bucket expr 

Convert logical address to physical address. 

Dump memory to lower diskette 

Display MMU information 

Set MMU information 

Set a value level #5 interrupt on a word change. 

Dump memory to upper diskette 

Displays the keycode of the NMI key 

Sets NMI keycode to expr 

Exits from the operating system * 

Set port number to expr. 

Print bug report on lower port 

Enable printing. 0=disable^ 1-upper port, 2-lower 

port 
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PS expr 

PT 

PU 

RB 

RS 

RT 

SB exprl exprlist 

SC expr 

SD 

SH 

SL exprl exprlist 

SM exprl exprlist 

SW exprl exprlist 

SY 

SY naT>e 

SY name expr 

T 

T expr 

TB addrl addr2 

TD 

UBR 

WP on 



Print screen. 0«aletmate, l»primary 

Print timing summary 

Print bug report on upper port 

Reboot 

Display the patch Return address Stack 

Reset timers 

Set memory in bytes with exprlist starting at exprl 

Stack Crawl. 

Set the default radix to decimal 

Set the default radix to hex 

Set memory in long words with exprlist starting at 

exprl. 

Set memory with exprlist starting at exprl. 

Set memory in words with exprlist starting at exprl 

Display the values of all symbols 

Display the value of the symbol name 

Assign expr to the symbol name 

Trace one instruction at the current PC 

Trace one instruction at expr 

Create Timing Bucket from addrl to addr2 

Display the Trace Display at the current PC 

User break* 

Disable (0) or Enable (1) Write Protection. 



* These are prcx;edure calls to Operating System procedures. They are 
explained in Section 8.2. 
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9.1 Exec Files 9-1 

Exec files are scenarios of commands to be automatically performed by 
the Workshop system. 

9JZ Exec File Statennents 9-2 

Exec file statements are of two types: normal lines^ that contain 
Workshop commands, and exec command lines, that tell how to process 
the exec file. Exec command lines include lines to set parameter 
values, perform input and output, and control conditional execution. 

9.3 Exec Files 9-14 

Exec files are invoked using the Workshop Run command. This 
invocation line can set the values of parameters, as well as select exec 
options. 

9.4 Example Exec Files 9-18 

This section contains examples of exec files, 

9.5 Exec File Programming Tips 9-22 

This section contains tips on writing exec files. 

9.6 Exec File Errors 9-23 

This section explains the format in which errors are reported, and lists 
the errors. 
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9.1 Exec Files 

Exec files are scenarios of commands to the Workshop system. They are 
contained in text files, created with the Editor, and are executed with the 
Run command. Exec files consist of characters you type to the Workshop to 
perform the functions you want, and special exec file commands, which enable 
you to use parameters and conditions to vary portions of the scenaria 

In its simplest form, an exec file contains the characters you press to perform 
a desired operation. An example of an exec file to compile a Pascal program 
is: 



$EXEC 



Pmyprog 



SENOEXEC 



{ You need to enter two blank lines here } 
{to run the Compiler > 



where P is the command to invoke the Pascal Compiler, and myprog is the 
name of the source file. Further lines to Generate, Link, and Run the 
program might follow. 

Two separate activities occur while running an exec file: processing and 
running. First, during process time, the exec processor creates a temporary 
file, which consists of a stream of Workshop commands. This temporary file is 
then sent to the Workshop, which executes the command stream at run time. 
A simple diagram of this procedure follows: 



exec file (s) exec processor 





temp file 



Workshop 



process time 



sum 


B 



run time 



With special exec file commands, you can use parameters and conditionally 
perform the Workshop commands. An example of an exec file for a simple 
Pascal program is shown in Figure 9-1. 
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$EXEC { "makeprog" — This exec file compiles, generates, and 
links a Pascal program. } 
P%0 

{ no listing file} 
{ default I-code file } 
GftO 

(default object file} 
L%0 

lOSPASLIB 

{ end of linker input } 
{ no list file } 
%0{ output file name } 
$ENDEXEC 

Figure 9-1 
Example Exec File 

You have several options avail^le to you when running the exec file 
processor. The Step Mode option^ which enables you to selectively skip 
command lines going to the temp file, could be used in the above example to 
choose whether to do only the compile, generate, or link. Section 9.3.1 
contains additional information on the exec file options. 

9.2 Exec File Statements 

Exec file statements are line oriented. Two types of exec file lines exist- 
exec caivti&id Ur^fs and nowiaJ lines. Normal lines contain Workshop 
commands. Exec command lines handle the other features of exec files, such 
as parameters and conditional statements. 

You can use up to 10 parameters in an exec file, numbered %0 through ?&9. 



parameter 

— (^^}— ( f"o ... 9 y -^ 

You can pass parameters when you invoke an exec file and use them during 
the execution of the exec file. For example, if you wanted to pass a 
parameter in the Example Exec File shown in Figure 9-1, you would Run: 

•qnakeprog (myprog) 

The value "myprog" would then be assigned at each reference to %0. 

When a parameter appears in a normal line, it is replaced by the string value 
of that parameter. These parameters can be used both as inputs to the exec 
file and as temporary variables within it. 
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Exec command lines start with a $ (dollar sign). They control the operation of 
the rest of the exec file. Exec command lines are free format, as long as the 
order of their elements is preserved. You can have any number of spaces 
before or after any element of a command line. These can go on to more 
than one line. The processor will look on the next line if it does not have a 
complete command at the end of a line. 

Normal lines contain commands for the Workshop system. These lines are sent 
to the workshop as they appear, with the following exceptions: 

1. Leading and trailing blanks are removed from these lines unless the "B" 
option is in effect. See section 9.3.1 for more on the "B" option. 

2. Comments are removed. 

3. Parameters are expanded. 

a. The tilde (~) literalizing character is processed. 

Comments are delimited by brackets { \, and can appear in either a normal or 
an exec command line. These can cross line boundaries. They can be used to 
comment out carriage returns in normal lines. 

The "~" is used as a literalizing character in normal lines, meaning it passes 
the character following it through without processing. With a tilde you can 
pass the character $, %, or { to the Workshop system without having it be 
interpreted as part of an exec command, a parameter, or a comment. To 
represent a tilde, use a double tilde (~~). 

Note that while the exec file processor is not case sensitive, it does preserve 
the case of parameters and strings supplied by the user. 

A description of each exec command follows. 

9.2.1 Beginning and Ending Exec Files 

Generally, exec files must begin with an EXEC line and must end with an 
EMDEXEC line. The exceptions to this basic rule, for those who embed exec 
files in their program sources, are: (1) one line of text can preceed the EXEC 
line if the I (Ignore) invocation option is used, and (2) any amount of text can 
follow the ENDEXEC line, but it is ignored. 

9.2.2 Setting Parameter values 

You can set parameter values in an exec file by using the SET and DEFAULT 
commands. The REQUEST command prompts the user for the value of a 
parameter. 
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9J2Z1 The SET and DEFAULT Commands 

The SET and DEF/VULT commands provide ways to change the value of a 
parameter inside of an exec file. The forms of these commands are: 



set statement 



- ($ set) — parameter 



itring expression 



and 



default statement 



- ($ DEFftULT ) — parameter 



c 



3 



(to) — string expression 



"String expression" is described in Section 9.2.5. 

The SET command changes the value of the specified parameter to the value 
of the given string expression. The DEFAULT command is similar to the 
SET command^ except that the assignment takes place only if the value of the 
specified parameter is the null string when the DEFAULT command is 
encountered. Thus, you can use this command to supply default values to 
parameters that have been left unspecified or empty in the exec invocation 
line. 

These commands also allow you to use unused parameters as variables within 
the exec file. 

9^.2^ The REQUEST Command 

The REQUEST command provides a way to prompt for values from the 
console. The form of this command is: 



request statement 



- ($ REQUEST ) — parameter 



Z) 



c 



(with ) — string expression 
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The REQUEST command prints the given string expression to the console, and 
reads a line, which it assigns to the specified parameter^ from the console. 
Thus, "str expr" prompts the user for the value. 

9J2.3 Input and Output 

You can request input to an exec file with the RE/NDLN and RE/>DCH 
commands. You can output values by using the WRITE and WRITELN 
commands. 

9.Z3.1 The READLN and READCH Commands 

The READLN and READCH commands enable exec files to read in text from 
the console, and to assign it to a parameter variable. You can use these 
commands to: 

• obtain parameter values 

• Obtain values to control conditional selection 

• pause until the user indicates to continue 
The forms of these commands are: 

readln statement 



- { $ READLN 3 — parameter 



and 



readch statement 



— ( $ READCH ) — parameter 



The RE/MDLN command reads a line from the console and assigns It to the 
specified parameter. The READCH command reads a single character from 
the console. If you press [RETURN], READCH will interpret it as a space. 

92.3-2 The WRITE and WRITELN Commands 

The WRITE and WRITELN commands enable exec files to write text to the 
console screen. You can use this text for inf ormatory messages or prompts. 
The forms of these commands are: 
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write statement 



string expression 



O 




and 



writeln statement 
-- ($~wiriteln} - 



string expression 



•O 




These commands take an arbitrary number of string expressions, separated by 
commas, as arguments. The strings are written to the current console line. 
The WRITELN command adds a final carriage return. 

92A Conditional Statements - the IF Statement 

Conditional statements enable you to perform commands depending on 
conditions existing at process time (when the temporary file is created). The 
condition is stated in the form of a boolean expression, and can include 
built-in boolean functions. 

The IF, ELSEIF, ELSE, and EMDIF commands enable conditional selection in 
exec files. The forms of these commands are: 



if statement 



if part 



elseif part 




$ ENDIF } -» 



else part 
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if part 



~ \$ IF ) — boolean express! 



on 



3 



-{ ^ THEN ) stuff 



elseif part 

— ($ ELSEIF ) — boolean expression 






^ THEN ) , Stuff 



else part 



- ($ ELSE ) — I stuff | -»' 



where "boolean expression" is described in Section 9.2.4.1^ and "stuff" is 
composed of arbitrary normal and command lines, otner than commands that 
would be a part of the current IF construct. The IF statement is multiline, 
meaning that the components IF, ELSEIF, ELSE, ENDIF, and "stuff" each need 
to be on separate lines. 

The IF construct is evaluated in the usual way. First, the boolean expression 
on the IF command itself is evaluated. If it is true, the "stuff" between the 
IF and the next ELSEIF (if any), or ELSE (if any), or ENDIF is selected; 
otherwise, it is not selected. The remaining parts of the IF construct, up to 
the ENDIF command, are parsed, but are not selected once one of the boolean 
expressions is true and its corresponding "stuff" is selected. Selecting "stuff" 
means that any normal lines are processed by the Workshop, and any command 
lines are processed. Conversely, if "stuff" is not selected, any normal lines 
and command lines are not executed. However, the command lines are parsed 
for correctness. 

If the boolean expression on the IF construct is not true, the ELSEIF or ELSE 
command that follows is processed. If an ELSEIF command is next, its 
boolean expression is evaluated. If true, its corresponding "stuff" is selected 
and the remainder of the IF construct is not selected. Processing the IF 
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construct continues until one of the boolean expressions on an IF or ELSEIF 
command is true, or until the ENDIF is reached. If no boolean expression is 
true before the ELSE (if any) is reached, the "stuff" corresponding to the ELSE 
command is selected. 

IF constructs can be nested within each other to an arbitrary level. 

9^.4.1 Boolean Expressions ~ Comparison and Logical operaton 

Boolean expressions enable you to test string values and check properties of 
files. The syntax for boolean expressions Is: 

boolean expression 




boolean term 



boolean factor 



^T}^ boolean expression -\) 




NOT 



boolean factor 
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The basic element of a boolean expression, a "bool factor", is either a boolean 
function (see Section 9.2.4.2) or a string comparison, testing string expressions 
for equality or inequality (see section 9.2.4.3). The basic elements can be 
combined with the logical operators AND, OR, and NOT, with parentheses for 
grouping. These operators function in the usual way. 

9.2.4.2 Boole^ Functions ~ EXISTS and NEWER 

Several functions returning boolean results are provided for use with the 
conditional contructs. 



boolean function 




(EXISTs3 -(r)- string expression -(^ 



NEWER ) -((/- string expression 




The EXISTS function enables you to determine whether or not a file, volume, 
or device exists. If you specify a device, the function will return a value of 
TRUE if the device has a volume mounted on it. "Oie string expression 
arguments to these functions should specify names of files. Typically these 
string expressions will be expanded string constants, discussed in Section 
9.2.43, such as "^l.obf. 

The NEWER function enables you to determine if one file is newer than 
another file; that is, whether or not its last-modified date is more recent than 
the last-modified date of another file. A value of TRLE is returned if the 
first file is newer than the second. During processing, an error will occur if 
one of the files does not exist. 



9.2.4.3 String Expressions 

A string expression can specify a 
following: 



string in a variety of ways, as noted in the 
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string expression 

..^^^^ 1 parameter ] 



"^ 



1 string constant j ^-^ 

-^-|expanaca string constantj- ^--^ 



-[ string function \- ->-^ 

I exec function call j- 



• A parameter ha^, the form %n. 

• A string constsnt has the standard form of text delimited by single quotes 
', with an embedded quote specified by the double quote rule, as in 'Thaf's 
all, folksi\ 

• An expanded string cxuistant is similar to a string constant, except that 
double quotes " are used as delimiters, and parameter references are 
expanded within the string. 

• A string function is an exec file processor function that returns a strinq 
value. A detailed description of string functions is provided in the 
following section. 

• An exec function caii is an invocation of an exec file that returns a 
string value, as described in Section 9.2.S.3. 

9.2.4.4 String Functions CONCAT and UPPERCASE 

The string functions CONCAT and UPPERCASE can be applied to other string 
expressions to produce new string values. 

The CONCAT function enables you to combine several string expressions to 
produce a single string result. The CONCAT function takes' a list of string 
expressions, separated by commas, as arguments. 

The UPPERCASE function converts any lowercase letters in its argument to 
upper case. 
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The form of these functions is: 
string function 

- (uppercase) — (7) — string expression — (7)- 
concat) — (r) 





An example of the use of the UPPERCASE function is 

$ SET *0 TO UPPERCASE (^ilO) 
which sets parameter to an uppercase version of its previous value. 

9^.5 Nesting Exec Files 

Exec files can be nested in two ways. One is to use the SUBMIT command to 
call another exec file in the same way that you would call a procedure. 
Alternately, you can call exec files as functions (returning string values to a 
string expression), as explained in Section 9.2.5.3. 

9.2.5.1 The SUBMIT Command 

The SUBMIT command enables you to nest exec files; that is, you can call 
one exec file within another exec file. The form of the SUBMIT command is: 

submit statement 

"\% SUBMir) — [exec command J--*- 

where "exec corrttnand" is en exec command of the same form as would 
follow the exec/ or < at the Workshop command level. This exec command 
can include parameters and exec options in the usual fashion (see Section 9.3). 

The SUBMIT connmand processes the specified exec file, putting any generated 
exec output text into the current exec temporary file. Thus, while a single 
exec file can have several nested subexec files, only one temporary output 
file is generated. This file contains the output generated by all of the input 
files. Exec files can be nested to an arbitrary level. 
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Within the text of the exec command, references to 5sn parameters are 
expanded, and the literalizing character tilde (~) is processed. Be aware that 
this is the only processing that takes place within the exec command. 
Everything up to the first left parenthesis, or the end of the line if no 
parameter list is present, is taken to be the exec file name. If a left 
parenthesis exists, the parameter list is taken to be everything between this 
parenthesis and the next right parenthesis. The exec command cannot be split 
across lines. 

Note that only the I (Ignore first line) and B (Blanks significant) options are 
valid on a SUBMIT command. The R (Rerun), S (Step mode), and T (Temporary 
file saved) options are applicable only from the main exec invocation line. 

9.2.5.2 The RETURN Command 

The RETURN command allows exec files to return string values to other 
(calling) exec files. Thus the RETURN command can transform an exec file 
into a function. The form of the RETURN command is: 

return statement 



- ^$ retur nT)- 



string expression 



Executing a RETURN command terminates the current exec file, and returns 
to the calling exec file with the specified string value. (Section 5.2.5.3 
describes how exec functions are called.) You can use a RETURN command 
without a string expression to exit from exec files which are not used as 
functions. 

One way you can use exec functions is to determine If a program file, 
including any corresponding include files, has been modified since its last 
compilation. This function can then be used to conditionally submit compiles. 
If written generally enough, such a function could be used by many exec files. 

Exec functions can produce side effects; that is, they can contain normal lines 
that get placed in the temporary file. While the intentional use of such side 
effects is unlikely, inadvertent instances can occur and are potentially 
hazardous to your exec files. An unexpected blank line in the middle of an 
exec file can often throw it out of sync. 

9.2.53 Exec Function Calls 

Exec function calls return string values, and are thus one of the basic 
elements of string expressions. They can also appear in boolean expressions, 
supplying arguments for string comparisons. A typical use of an exec function 
is to return a boolean value by returning either the string T or F. The form 
of an exec function call is: 
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exec function call 
— (<) — f lien 



ame 



parameter list 



parameter list 



^ 



^ 



text 



O 



where < is the character that signals a function invocation, in the same way 
that this character identifies exec files for the Workshop's Run command. 
The "file name" and optional "parameter list" are the same as described in the 
SUBMIT command section. Section 9.2.5.1. 

Due to the liberal conventions concerning what characters, including blanks, 
can appear in file names, the exec file processor must make some assumptions 
about how to identify the exec function file name and the argument list. 
The following rule Is used: if the exec function invocation has an argument 
list, tr« file name is assumed to be everything between U« "<" and the "(" 
beginning the argument list; otherwise, the file name is assumed to be 
everything between the "<" and the end of the line. This means that if the 
function call is not the last thing on the command line, you must supply an 
empty argument list to an exec function with no arguments. 

Processing the text of a function call is the same as with a SUBMIT 
command; that is, the only processing that takes place is the expansion of ?i6n 
parameters and recognition of the literalizing character """. This means that 
the text of a function call cannot contain an embedded function call. Note 
also that a function call camot be split across lines. 
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9.3 Using Exec Files 

You invoke the exec file processor in response to the Workshop Run commana 
prompt. An invocation line for the exec file processor has the form: 

exec invocation line 




exec command| --»- 



exec command 



filename 



parameter list 



exec options 



The "exec file" is the name of the exec file you want to run. An extension of 
".TEXT" is assunned if no extension is specified. However, you can override 
the mechanism that supplies the ".TEXT" extension by ending your exec file 
name with a period; for example, using "foo." causes the exec file processor to 
search for the file "foo" rather than "foo.text". 

The optional "parameter list" is enclosed in parentheses. The parameter list 
can be empty or it can include up to ten parameters separated by commas. 
For example, an exec file to run compiles, which takes volume and source file 
parameters, might be invoked with "compIle(foo,-work)". You can omit 
parameters, leaving them as null parameters, by specifying them with the null 
string, as in "compile(foo,)". The volume that was present in the previous 
example has been omitted. Alternately, parameters can be left unspecified 
altogether, as in "compile(foo)". In this case, they also get null values. One 
reason to omit parameters is that the exec file might have been set up to 
supply default values, as described In Section 9.2.2.1. 

The exec options that follow the closing right parenthesis of the parameter 
list consist of single-letter commands, which change the behavior of the exec 
file processor; for example, you use the letter S to indicate that you want to 
step through the exec file as it is being processed, conditionally selecting 
which commands are to be sent to the Workshop. The exec options are 
discussed in detail in Exec Invocation Options, Section 9.3.1. 
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The exec file processor's output is a temporary file with a ". .text" extension. 
The temporary file is the processed version of your exec commands; that is, 
all exec command lines have been processed and removed, leaving only the 
resulting Workshop commands. This temporary file is passed to the Workshop 
when the processing is completed. The Workshop then runs the temporary 
exec file, and automatically deletes it when finished. 

NOTE 

To terminate the processing of the exec file while the exec file 
processor is running, you press «^-period. 

9.3.1 Exec Invocation Options 

Several options are available when running the exec file processor. You can 
specify these options when invoking the exec file processor or on SUBMIT 
commands. The options are specified by single letter commands following the 
exec parameter list. A null parameter list should be used if you want to use 
options without parameters, as in "<fooOs". The options are as follows: 

B indicates that the exec file processor should not trim blanks on output 
lines. Normally the exec file processor trims off leading and trailing 
blanks on the lines that it outputs to the temporary file. Trimming 
enables you to indent normal lines (lines that are not exec command lines) 
without worrying about generating spurious blanks. In other words, the 
exec file processor assumes that leading and trailing blanks are 
insignificant While this assumption is true for Workshop commands, it 
might not be true for some other programs you can run with exec files. 
Using this option tells the exec file processor not to trim such blanks. 
The option applies to only the exec file being run or SUBMITted, and not 
to any nested exec files. 

I indicates that the first line of the exec file is to be ignored by the exec 
file processor. This option is intended for those who embed exec files in 
their program sources. When using this option, you should begin the first 
line of the source with a "(*", and follow the end of the exec file with a 
"*)", thus commenting it out of the program sourcer Note that you should 
use "(*" and "*)" instead of "{" and "}", since the latter are comment 
delimiters in exec files. 

T indicates that the temporary file, which is created (i.e., the expanded form 
of the exec file), should not be automatically deleted after it is run. This 
option enables you to to rerun an exec file created with the step option 
(see below) without going through the stepping prompts a second time by 
running a previously created expanded exec file. The R exec option, 
described next, is used to run old temporary exec files. Note that the T 
option is not allowed on SUBMIT commands. 
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R indicates that the an exec temporary file^ saved with the T option, should 
be rerun, bypassing the normal processing by which the temporary was 
created. For exanrple, "foo" might be an exec file that generates a 
complicated system using a large number of nested exec files that take a 
significant amount of time for the processor to digest. If you know you 
are going to run "foo" repeatedly, you might want to generate the 
temporary file only once but run it several times. The first time you 
would invoke the exec file processor with "<fooOt" to indicate that the 
temporary file should not be automatically deleted after it is run. 
Subsequently, you would invoke the exec file processor with "<fooOr" to 
rerun the old tenporary file. Note that the R option overrides any others 
that might be specified; since, if you are rerunning an old exec temporary 
file, all the processing has been performed and the other options make no 
sense. Using the R option is not allowed on SUBMIT commands. 

S indicates that the exec file should be processed in "Step Mode", which 
allows selective skipping of output lines and SUBMITS. 

9.3.1.1 Using the Step FuncUon 

If you use the step option, the following prompts appear when you invoke the 
exec file processor: 

step Mode: 
— in response to "Include ?" answer: 

Y, N, A (Abort), K (Keep rest), or I (Ignore rest). 
~ in response to "Submit ?" answer: 

Y, N, S (Step), A (Abort), K (Keep rest), or I (Ignore rest). 
More details ? (Y or N) [No] 

If you repond with Y (yes) to the "More details ?" prompt, you get 
additional information as to what each of stepping responses means. 

When you invoke an exec file wiUi the step option, you are prompted when a 
line has been generated and is about to go into the temporary file. The line 
is displayed followed by "<- Include ?". 

• A response of Y includes the line in the expanded exec file. 

• A response of N omits the displayed line. 

• A response of A aborts out of the exec file processor, and no exec file is 
run. 

• A response of K keeps (includes) all the remaining lines of the exec file, 
leaving step mode. 

• A response of I ignores the remainder of the exec file. No more lines are 
included. 
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When a SUBMIT command is encountered in stepping, the SUBMIT line is 
displayed followed by "<= Submit ?'". 

• A response of Y performs the SUBMIT unconditionally; that is, without 
stepping through it. 

• A response of N ignores the SUBMIT. 

• A response of S steps through the SUBMIT file. 

• A response of A aborts out of the exec file processor, and no exec file is 
run. 

• A response of K keeps the rest of the exec file, leaving step mode. 

• A response of I ignores the remainder of the exec file. 

NOTC 

A reponse of ? to a "Submit ?" or "Include ?" prompt elicits an 
explanation of the accepted responses. 

Some examples of how to use the exec file processor's stepping facility follow. 

Stepping can be used to resume execution of an exec file that did not run to 
termination. For example, if your "compile" exec file includes both a compile 
and a generate step, and if you want to resume with the generate step, you 
invoke the exec file with "compile(foo,-work)s". Then, in response to the 
"Include?" prompt for lines corresponding to the compile step, you hit N to 
skip the lines. Upon reaching the first line of the generate step you respond 
with K to keep the rest of the file. Thus the generate step of the exec 
process would be performed. 

The stepping mechanism can be used to run only selected parts of an exec 
file. Say, for instance, that you have a modular set of exec files, which 
generates a whole system of programs, such as the Workshop, and that one 
exec file called "m^e/all" can generate the whole system by SUBMITting 
exec files for each of the component programs. The exec files for each 
ccMTponent program (development system tool) make use of other exec files to 
perform such standard activities as compiling (and generating) a Pascal unit or 
program, performing an assembly, installing a library, or manipulating files 
with the Workshop's filer. If you perform a system build and find yourself 
constently having to regenerate parts of the system, the ability to step by 
SUBMITS proves very useful. You can regenerate arbitrary parts of the 
system by running "<make/allOs" (our master exec file invoked with the 
stepping option), and selectively submitting the subexec files for only those 
things that you want to rebuild, while stepping over the others. 
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Stepping in conjuctioh with the T option, for saving the temporary file created 
by the exec file processor, can be useful when you are igoing to be 
regenerating a single component of a program or system a number of times in 
succession; for example, when you are fixing a bug in an element of a system 
build and you expect that several iterations will be needed to correct the 
problem. To continue the previous example, suppose that while building the 
development system, you have a problem with the "fileio" unit of the 
"objiolib" library. Suppose also that an exec file called "make/objiolib" 
generates and installs the library, submitting compiles and assemblies for all 
of its units, linking everything together, and finally performing the 
installation. By invoking the exec file processor with "make/objiolibQst", you 
can go into step mode and submit only those things related to the compilation 
of the "fileio" unit, the link, and the installation of the library in the intrinsic 
library. Then, after each successive refinement of "fileio", you can run the 
saved temporary file by running "<make/objiolibOr" without having to go 
through the stepping process. The alternatives to this procedure are: to 
create another exec file to generate only the selected parts, to run (and rerun) 
the exec file for the whole library, or to run each subprocess independently 
(which requires more of your attention). 

9.4 Example Exec Files 
9.4.1 An Exec File to Do a Pascal Compile 

This exec file does a Pascal compile and generate. Note how comments are 
used to make the single character Workshop commands more intelligible. 

$EXEC { "corap" — perform a Pascal conplle 

*0 -- the name of the unit to compile } 
P{Pascal compile }%0{source} 

{no list file) 

{default i-code file} 
6{generate code}%0 

{default obj file} 
SENDEXEC 

9.4J2 An Exec File to Do an Assembly 

This exec file performs an assembly, and allows for an optional output file 
name which can be different from the source name. 

$EXEC { "assemb" — perform an assembly 

%0 - the name of the unit to assentjle } 
tl — (optional) alternate name of OBJ output } 
SOEFAULT X\ TO XO { use source name if no output name is given} 
A{assent)le}%0{source} 
{no list file} 
%l{obj file} 
SENDEXEC 
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9A3 A More Flexible Exec File to Do Pascal Compiles 

This exec file performs compiles, allowing for an output file witn a different 
name than the souce. 

$EXEC { "conpi" ~ perform a Pascal compile 

\0 — the name of the unit to conpile 
\\ ~ (optional) alternate name for OBJ file } 
$DEFAULT W. TO %0 { If no alternate OBJ name use same name as 

source} 
P{Pascal coinpile}%0{source} 
{no list file} 
{default i-code file} 
G {generate code}%0 

*1{0BJ file} 
$ENDEXEC 

9.4.4 A "Smart" Exec File to Do Pascal Compiles 

This compile exec file only performs the compile if either the object file does 
not exist or the source file is newer than the object file; that is, the source 
has changed since it was last compiled. It uses the compl exec file shown in 
Section 9.4.3 above. 

$EXEC { "comp2" ~ perform a Pascal compile (only If really 
required) 
*0 ~ the name of the unit to compile 
*l ~ (optional) alternate name for OBJ file } 
$DEFAULT *9 TO %l { set *9 to name of output OBJ file } 
SDEFAULT *9 TO *0 
$IF EXISTS (n9.0bj") THEN 

$IF NEIER ("*0.text","%9.0dJ") 

THEN {recomp if source newer than object} 
SsuBttiT coirpi(%o.5i;i) 

SENDIF 
SELSE { OBJ file does not exist, so generate it } 

SSUBHIT compl(^0,«l) 
$ENDIF 
$ENDEXEC 

9.4.5 Exec File Chaining 

This example, "make/Prog", uses the smart compile exec file C'comp2") 
defined in the last example to demonstrate how to chain exec file execution. 
Assume you want to generate a particular program composed of three units 
(unitl, unit2 yx\\\3\ and that you have written "link/Prog", a smart exec file 
which performs a link only when one of the object files for one of the units is 
newer than the linked program file. Your generation exec file uses these 
smart exec files to perform the minimal required amount of work. Thus it 
can be used to ensure that you have the latest version of the program without 
performing a full regeneration. 
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$EXEC { "make/Prog" ~ smart version, only reconpiles 

& links when it has to} 

SSUBMIT coinp2(unitl) 

$Sl)BMIT coinp2(init2) 

SSUBMIT coinp2(unit3) 

R<link/PrGg { Run link exec file after compiles have 

run so that it gets the correct file 
dates. This is one exanple of when you 
should note the difference beti#een 
process time and run time.} 
SENDEXEC 

Note that in the last line of the above exec file you have scheduled an exec 
file to be run at a later time, as opposed to SUBMITting it now, so that the 
file dates for the link step are accessed after the compiles have had a chance 
to run. The differences between running and submitting and exec files are 
demonstrated in the following scenario. When an exec file is submitted, it is 
processed immediately by the exec file processor. Its output goes to a 
temporary file, which is then passed back to the Workshop. The Workshop 
runs the commands in the temporary file until it comes to the command to 
Run another exec file. At this point it discards the remainder of the 
temporary file, and runs the exec file processor with the new exec command. 
This exec file invocation results in another temporary file of commands, which 
is then run by the Workshop. This means that some exec processing has been 
scheduled to follow some exec running, rather than all of the processing 
taking place first 

9.4.6 A Recursive Exec File to Do Pascal Compiles 

This compile exec file performs up to 10 compiles. It takes an argument list 
with the names of the units to be compiled. 

$E}EC { "rconp" ~ perform any number (up to 10) Pascal compiles. 
It calls "comp" on its first argument aid then calls 
itself recursively with its arguments shifted left } 
$IF %0 <> "• T>EN 

$SUBmT comp(%0) { "conp" the first one } 
${ "rcomp" the rest, less first } 
$SUBMIT rcomp(%l,%2,%3,U,%5,%6,%7,%8,*9) 
$EhDIF 
$ENDEXEC 

9A7 A BASIC Example 

This exec file demonstrates, by generating the BASIC Interpreter, some of the 
constructs in the exec file processor's meta language. The comments in the 
body of the example should be sufficient to describe what is taking place. 
The essential idea is that BASIC is made of three components and that you 
might want to generate only one or two of them at a time. 
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SEXEC { "make/basic" ~ generate the BASIC Interpreter. 

There are three parameters ~ if a parameter is a "Y" 
(yes) the corresponding part of the system should be 
generated: 

(0) the b-code interpreter 

(1) the run-time system 

(2) the command interpreter 

If no parameters are specified^ the exec file prompts to 
see Khat parts of the system should be generated. } 
SiRITELN 'Starting generation of the BASIC system' 
$IF %0 = " AND %1 = " AND %2 = ' • THEN 

$ {no params supplied ~ prompt for info} 

SPRITE 'do you i»ant to assemble the b-code interpreter?', 
'(y or [n])' 

$REAOCH «0 

SiRITELN { this writeln puts us on a new line for the next 
prompt } 

SKRITE 'do you »»ant to compile the run-time system!?', 
•(y or[n])' 

$REAOCH XI 

$«RITELN 

$VRITE 'do you want to compile the command interpreter?', 
'(y or [n])' 

SREADCH t2 

SiRITELN 
SENDIF 
S 
SIF UPPERCASE(*0) = 'Y' THEN {asseirble the b-code interpreter} 

SSUBHIT assent) (int. main) 
lENDIF 
S 
SIF UPPERCASE(*l) = 'Y' THEN { compile the run-time unit } 

SSUBHIT corap(b.rtunit) 
SENDIF 
S 
SIF UPPERCASE(%2) = 'Y' OR UPPERCASE(%1) = 'Y' THEN 

S{ compile the command interpreter } 

S{ compile also if the run-time unit has changed } 

SSUBHIT comp(b. basic) 
SENDIF 
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■■ $ ■ 
${ link it all together } 

L{link}b. basic 

b.rtunit 

int. main 

hnintl 

iosfplib 

ios(»slib 

basic{executable output} 
lENDEXEC 

9A8 An Exec File Function 

This exec file is a function which prompts the user for the location of a 
ProFile, and returns a string with the name of the device to which the Profile 
is attached. Note that the function calls itself recursively until a valid 
device name is specified. 

$EXEC { "GetProfLoc" ~ get location of ProFile by asking user } 
$REOUEST %9 WITH 

'•here is the ProFile attached (par^port/slot2ch»il/slot2ch»i2)' 
$SET %9 TO UPPERCASE (%9) 

$IF (%9 <> 'PARAPORT') AND (*9 <> •SL0T2CHAN1') 
AND (%9 <> •SLGT2CHAN2') THEN 
$WRITELN '"mat is not a valid device name. Lef's try again.' 
$RETURN <GetProfLoc { recursive function call } 
$ELSE 

$RETURN «9 
$ENDIF 
lENDEXEC 

9.5 E)«c File Programming Tips 

The following points might be useful to remember when creating exec files. 

1. Use moduJar exec files. Think of exec files ^z proc&Jures that are 
called by the SUBMIT command. The more modular your exec files are, 
the easier it is to use the stepping facility on them. 

2. Create standard exec files for common functions; for example, use one 
exec file to perform all your compilations. Therefore, if changes become 
necessary, you have only one place to change. 

3. Use optional par^neters to support features of your exec files that you 
do not always use. The parameter mechanism enables you to ignore 
optional parameters if you do not need the functions they support 
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a. Write your exec files tx) prompt for infiormation not supplied in the 
parameters. Thus you do not need to remember the meaning of a large 
number of parameters. 

9.6 Exec File Errors 

The exec file processor can recognize a number of errors during its invocation 
and executioa The format in which errors are reported is: 

ERRCR in <err loc> 
<curr line> 



where 



<err marker> 
<err msg> 

<err loo is either "invocation line' or "line #<n> of file "<file>". 

<curr line> is the text of the current exec line where the error was 
detected. 

<err marker> is a line with a question mark indicating where the exec 
file processor was in <cun line> when the error was 
detected. 

<err msg> is one of the messages listed below. 

I/O errors are followed by an additional line with the text of the OS error 
raised during the I/O operation. The errors detected are listed below. 

9.6.1 I/O Errors 

Unable to open input file "<file>". 
Unable to open temporary file "<file>". 
Unable to access file "<file>". 
Unable to rerun file "<file>''. 

9.6.2 Other Errors 

File does not begin with "$EXEC". 

End of Exec file before "$ENDEXEC". 

$EXEC command other than at start. 

No Exec file specified. 

More than 10 parameters. 

No closing ")" found. 

Line buffer overflow (>255 chars). 

Invalid Exec option: <option char>. 

Invalid Exec oJDtion on SUBMIT: <option char>. 

End of Exec file in coirment. 

Invalid percent: not "Xn" form. 

Garbage at end of command. 

No argument to SUBMIT. 

ELSE, ELSEIF, or ENDIF not in IF. 

ELSEIF after ELSE. 

File contains unfinished IF. 
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Nothing following "<tilde>". 
Out of memory. Processing aborted. 
Bad temp file name generated: "<file>". 
No value returned from file called as function. 
RETURN with value in file not called as function, 
and 

Invalid command. <token> expected, 
where <token> might be: 

String value 

"%n" parameter 

Terminating string delimiter 

"=" or "<>" 

Boolean value 

Comma (list delimiter) 
II / II 

")" 

Valid command keyword 

Command 
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10.1 Introduction 10-1 

The Transfer program is a communications package that allows you to 
transfer text between your Lisa and a remote computer. 

lOJZ Hardware Connections and CXmflguration 10-1 

To use the transfer program you need a modem connected to one of 
the serial ports. Use the Preferences tool from the System Manager to 
configure the Lisa to use the modem. 

10-3 Setting Transfer Program Characteristics 10-1 

Use the menus to set the baud rate, parity, handshake, and full or half 
duplex so that the transfer program will be compatible with the remote 
computer. 

10.4 Using the Transfer Program 10-5 

The transfer program can be used to transfer a file from a remote 
computer to the Lisa, or from the Lisa to the remote corrputer. It can 
also allow you to use the Lisa as a terminal connected to the remote 
computer. 
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lai Introduction 

The transfer program is a data communications package that allows you to 
transfer text files from your Lisa to another computer. You can also receive 
text from the remote computer and store it in a text file, which can then be 
read by the Editor. 

To use the transfer program, you must either: 

• Get the necessary modem and attach it to the Serial A or Serial B 
connector on the back of your Lisa. Then tell the Preferences tool in the 
System Manager the you are attaching to a Remote Computer. 

• Or, get the necessary modem eliminator cable and attach it to the Serial A 
or Serial B connector on your Lisa Then attach the other end to a serial 
port on another computer, and tell the Preferences tool that you are 
attaching to a Remote Computer. 

When you have completed either action, set the Transfer Program 
characteristics to match the requirements of the remote computer. 

These operations are explained in Sections 10.2 and 10.3 below. Section 10.4 
explains how to use the Transfer Program to send and receive data 

10L2 Hardware Connections and ConflgLiratlon 

In order for the Lisa to communicate to a remote computer the Lisa can be 
connected to a modem or a modem eliminator cable through either the Serial 
A or the Serial B connector on the back of the Lisa. 

In acWition to connecting the hardware, you must configure the software To 
do this, use the Preferences tool from the System Manager command line. 
Access the Device Connections display, and set either Serial A or Serial B to 
Remote Computer. More information on the Preferences tool can be found in 
Section 3.3. 

You must also set the active Transfer Program to access the correct 
connector. Do this by selecting either Serial A or Serial B from the 
Connector menu. The default is Serial A 

103 Setting Transfer Program Characteristics 

In order to communicate with, a remote computer, the Transfer Program must 
be set up so that it transmits and receives data in the same way as the host. 
These settings are made by using the Baud Rate, Parity, Handshake, Duplex, 
and Control menus. These settings are explained below. 
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Baud Rate 

The baud rate is the speed at which data passes to and from the remote 
computer. The baud rate must be set to agree with the remote computer and 
modem you are using. The baud rate menu is shown in Figure 10-1. The 
default is 1200 baud. See the note in Section 11.10, PortConfig, for the vaiid 
baud rate settings for each Serial port 



Baud Rote 



50 
75 
110 
134.5 
150 
200 
300 
600 
yi200 
1800 
2000 
2400 
3600 
4800 
9600 
19200 



Figure lO-l 
TTie Baud Rate Mem 

Parity 

Parity refers to the process of checking that data was not damaged in 
transmission. Parity should be set to agree with the host computer. Parity 
can be even^ odd, or turned off (rrane). Select the option desired from the 
Parity menu. The default is none. The parity menu is shown in Figure 10-2. 
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Figure 10-2 
Ttie Parity Menu 

Handshake 

The handshake menu, shown in Figure 10-3, selects either an XOn/XOff 
protocol, or no handshake. The XOn/XOff protocol allows the remote computer 
and the Transfer Program to tell each other whether they are ready to 
receive more information. Using this protocol, the Lisa can stop transmission 
from the host t)y sending XOff, and start it again by sending XOn. The host 
can start and stop transmission from the Transfer Program by sending XOn 
and XOff to the Lisa. The XOn character is a control-Q, XOff is control-S. 
The default is for handshaking to be turned on. 



Handshake 



None \ 
yXOn/XOff 



Figure 10-3 
The Handshake Menu 

Duplex 

This menu allows you to select Full or Half duplex. Full duplex sends all 
characters typed from the Lisa keyboard to the remote computer, but does not 
display them on the Lisa screen. All characters sent from the host are 
displayed on the screen. Using full duplex, you will only see what you type if 
the remote computer sends back the characters you type. Most hosts you are 
likely to use with a Lisa do send back the characters they receive to be 
displayed. 

Half duplex displays the characters typed on the keyboard, because it does not 
expect the host to send them back. The default is full duplex. The duplex 
menu is shown in Figure 10-4. 
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Figure 10-4 
The Duplex Menu 

Control 

The control menu allows you to set two delay times, if needed. The first is a 
delay between each character sent, the second is the delay between each line. 
Both are in milliseconds. Delays are used to simulate typing speeds when 
transmitting to a remote computer that can not keep up with full speed 
transmission. The default is for no delay. The control menu is shown in 
Figure 10-5. 



Record to 



Record fill Text 
VRecord Filtered Text 



Play Back from 
Character Delay 
Line Delay ... 



Exit 



Figure 10-5 
The Control Menu 
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ia4 Using the Transfer Program 

Start the Transfer Program by pressing T in response to the Workshop 
command line. The Transfer Program will display a window on the screen 
with menus at the top. You must configure the Transfer Program to match 
the remote computer you wish to communicate with. Information on 
configuring it can be found in Section 10.3 earlier in this chapter. 

After the Transfer Program comes up, it is ready to act as a terminal 
emulator. Evrything you type on the keyboard will be transmitted through the 
modem to the remote computer. 

The Transfer Program can also be used to transfer files back and forth 
between the Lisa and the remote computer. The functions for doing this are 
in the Control menu. The control menu is shown in Figure 10-6. 

To transfer a file from the Lisa to the remote computer, select "Play Back 
From . . ." from the control menu. It will ask you for the file name to play 
back. It expects a .TEXT file. The contents of that file will be transmitted 
to the remote computer. 

To transfer a file from the remote computer to the Lisa, select "Record to ..." 
from the control menu. It will ask you for the name of the file to record to. 
After you have set up the remote computer to transmit the file you want (by 
typing commands at the keyboard) select "Record All Text" from the control 
menu. When you tell the remote computer to transmit the file, it will be 
recorded in the file you specified. This command will record the file exactly 
as transmitted, including all control characters. If you don't want the control 
characters, select "Record Filtered Text". This option changes carriage 
returns to newlines and replaces tabs by the appropriate number of spaces. 
All other control characters are thrown away. The filtering option affects 
only the disk file, not what is displayed on the screen. The default is "Record 
Filtered Text". 

To transmit control characters from the keyboard, hold down the %, key and 
press the character. Other special purpose characters can be transmitted as 
shown in Table 10-1. Option keys are treated as no-ops. 
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Table lQ-1 
Transmitting Special Characten from the KeytxDard 



Keytjo&ra 


Tmmmtts 


Apple tsackspace 


del 


clear 


esc 


ENTER (alpha keyboard) 


break 


ENTER (numeric keypad) 


return 


arrow keys 


their symbols 


Apple Q 


XOn 


Apple S 


XOff 
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11.1 ByteDiff 11-1 

ByteDiff compares two files, byte by byte, and shows where they are 
different. 

11.2 ChangeSeg 11-2 

ChangeSeg allows you to change the segment names in the models in 
an unlinked object file. 

11.3 CodeSize 11-3 

CodeSize gives you a summary of the contents of an object file 

11.4 Diff 11-6 

Diff compares two text files and shows their differences. 

11.5 DurrvCDj 11-8 

DumpObj displays the contents of an object file. 

11.6 DumpPatch 11-9 

DumpPatch displays and edits the contents of any file. 

11.7 FileDiv and FileJoin 11-11 

FileDlv divides large files into smaller ones. FileJoin rejoins the 
resulting small files back into the original large file. 

11.8 Find .....11-12 

Find searches a text file for a pattern, such as identification. 

11.9 GXRef 11-13 

GXRef provides a global cross reference of subroutines and modules. 

11.10 PortConfig 11-14 

PortConfig enables you to configure the RS232 ports. 

11.11 SegMap 11-16 

SegMap produces a segment map for one or more object files. 

1L12 SXRef 11-17 

SXRef produces a cross reference of source files. 



?-A 



11.13 UXRef , 11-18 

UXRef producses a cross reference of USES statements in programs 
and units. 



The Utilities 



11.1 ByteDiff 
Synopsis 

ByteDiff compares the contents of two files and reports which bytes (words) 
are different. 

Dialog 

Source file? 
Target file? 

Description 

ByteDiff compares the source file to the target file and reports on their 
differences. This utility is useful for finding the first differences between 
files or for finding a small number of differences. 

T?ie program prompts for on input file arxi an output file. The two files can 
be in any format .text, .obj, X and so forth. 

The output is of the form: 

Bytes $xxxxxx differ aaaa bbbb 

where; 

xxxxxx is the byte address in hex 

aaaa is the word (two bytes) from the source file 

bbbb is the word from the target file 

After 20 lines of output the user can either terminate by pressing [CLEAR] or 
continue by pressing the space bar. 

See Also 

Diff, E(qual commaid of the File Manner 

Notes 

ByteDiff compares any binary files, but once it finds a difference between the 
two files, it does not try to resynchronize. This utility does block-at-a-time 
1/a The program stops at the fint end-of-file and has no termination 
message. ByteDiff is nonstandard user interface. 
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11^ cnangeSeg 
Synopsis 

ChangeSeg changes the segment name In the modules In an unlinked object 
file. 

Dialog 

File to change: 
Map all Names (Y/N) 

Description 

The fint prompt asks for the mlinked object file you want to change. 

You are next asked if you wait to map all names. If you wait to change 
segment names in all nrKxIules, respond Y. If you want to be prompted for the 
new segment name for each module^ type N. A response of [RETURN] accepts 
the default name. 

Notes 

Changes are made In place (the file Itself is changed)L 
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11.3 codesize 
synopsis 

Determines me code size and code segmentation for a unit^ a program^ or a 
library. 

Dialog 

input file [.OBJ] - 

Resident file [.TEX"n - 

output file [-CONSOLEM.TEXT] - 

The resicfent file is the file that contains the segemnt names that are 
considered resident. The names in the file must he the same case as in the 
code file itself. The resident information is used in the simmary reports to 
automatically sum the resident and swapping code. 

At any time when specifying the file names, the run-time options can be 
turned on or off. The run-time options are: 

+% turns the mapping of calls to system externals on or off. System 
externals are procedures whose names begin with a "56". Using this 
option, the system will count the number of procedures that call a 
particular system external. This option is used to determine which 
system routines are being used, for example, if WRITELNs are left 
in the code. 

+E turns the mapping of calls to nonsystem externals on or off. 

Nonsystem externals are procedures in a segrr^nt other than tf« 
calling procedure. Using this option, the system will count the 
mmber of procedures that call a particular nonsystem exterr^l. 
This option is used to determine which routines are being used, for 
example, which library routine the code is usir^. 

+M tells CodeSize that a particular segment is mapped onto another 
segment. This information generates the segment mapping summary 
and the segment summary. This option is used when smaller 
segments are mapped into larger segennents, and the sizes of the 
smaller and resulting larger segements are needed. 

+S turns the main report on and off. Sometimes the summary report is 
all that is meded. Use this option to print only the summary 
report. 

Description 

CodeSize generates two types of reports depending on the type of input file(s> 
main report and summary report. The input file can be an execution file, a 
library, or an object file. For each file, the report format will be: 
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Type of File 

Execution file 

Library file 
Object file 



Main Report 

segment informatim 

unit information 
segment information 

unit information 
procedure informatim 



Summary Report 

segment summary 
main summary 

unit summary 
segment summary 
main summary 

external summary(+E or ♦%) 

unit summary 

segment mapping summary(*M) 

segment summary 

main summary 



The contents of the report section are: 



Segment information 
segment type 
segment name 
segment size 

Unit information 
unit name 
unit global size 
unit type 

Procedure information 
procedure name 

associated segment 
procedure size 
interface information 

external references 



External summary 

external procedure name 
# of occurrences 



Unit suTTvnary 
unit name 
unit size 
unit type 
unit global size 



intrinsic, nonintrinsic, main program 

first eight charcters of the segment's name 

size of the segment in decimal or hex 

first eight characters of the unit name 
hoy much global space the unit uses 
intrinsic, shared intrinsic, regular 

first eight characters of the procedure's 

name 

first eight characters of its segment's name 

size of the procedure in decimal or hex 

is the procedure in the interface of the 

unit? 

list of all the external calls the procedure 

makes. This is triggered by the +E or +% 

options 

name of the procedure 
how many different procedures called the 
procedure. This is triggered by the +E or 
♦% options. 

first eight characters of the unit's name 
size of the unit in decimal or hex 
intrinsic or not 
how much global space the unit uses 
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Segment mapping summary 
original segment name 
new segment name 
segment size 

Segment summary 
segment type 

segment name 
segment size 

Main summary 
total code size 
total resident code 



total swapping code 

total data globals 
total main prog globals 

total globals 

total Jump table 



name of tne original segment 
name the segment is being mapped into 
size of the segment being mapped. This is 
triggered by the ♦M option. 

swapping or resident. Resident segment is 
specified to CodeSize by the "resident file", 
first eight characters of the segment's name 
size of the segment in decimal or hex 

summation of the code size 

siffnmation of the code that is considered 

resident all the time. Resident code is 

specified to CodeSize by "resident file". 

summation of the code that is considered 

swapping all the time. Swapping code is 

specified to CodeSize by "resident file." 

summation of the global space for data 

summation of the global space in the main 

program 

sum of main program globals plus data 

globals 

size of the jump table 
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11.4 Cttff 

Synopsis 

Diff Is a program for cornparlng .TEXT files, in Uie Workshop. Diff is 
designed to be used with Pascal or AssemDler source files. 

Dialog 

(Type '?* to change or display options.) 



New file name [.TEXT 
Old file name [.TEXT 
Listing file [.TEXT 



(<CR> = -CONSOLE) - 



Description 

Diff fint prompts you for two input file names: the "new" file, and the "old" 
file. Diff appends ".TEXT" to these file names, if it is not present. Diff then 
prompts you for a filename for the listing file. Press [RETURN] to send the 
llstinig to the console. 

Diff does not know about INCLUDE files. However, Diff does enable the 
processing of several pairs of files to te sent to the same listing file. Thus, 
when Diff is finished with one pair of files, it prompts you for another pair of 
input files. To terminate Diff, simply press [RETURN] in response to the 
prompt for a new file name. 

The output produced by Diff consists of blocks of "changed" lines. Each block 
of changes is surrounded by a few lines of "context" to aid in finding the lines 
in a hard-copy listing of the files. 

There are three kiixls of change blocks: 

INSERTION a block of lines in the "new" file which does not epjear 

in the "old" file. 

DELETION a block of lines in the "old" file which does not appear in 

the "new" file. 

REPLACEMENT a block Of lines in the "new" file which replaces a 
corresponding block of different lines in the old file. 

Large blocks of changes are printed in summary fashion: a few lines at the 
beginning of the changes and a few lines at the end of the changes, with an 
indicatim of how many lines were skiiped. 

Diff has three options: 

C change the number of context lines displayed. 

M the number of lines required to constitute a match. 

D the number of lines displayed at the beginning of a long block 
of differences. 
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To set one of these numbers, type the option name and [RETURN], followed Dy 
the new number to the prompt for the first input file name. An entry of D 
[RETURN] 100, for example, causes Diff to print out up to 100 lines of a 
block of differences before using an ellipsis. The maximum number of context 
lines you can get is 8. You can get a display of the current option settings 
by pressing "?" in response to the first file prorrpt. 

Diff is not sensitive to ipper/lower case differerces. All irput is shifted to a 
uniform case before comparison is done. This is in conformance with the 
language processors, which Ignore case differences. 

Diff is not sensitive to blanks. All blanks are skipped during comparison. 
This is a potential source of mdelected changes, since some blaiks are 
significant (in string constants, for instance). However, Diff is insensitive to 
trivial changes, such as indentation adjustments, or insertion and deletion of 
spaces around operators. 

Diff does not accept a matching context which is too small. The current 
threshold for accepting a match is 3 consecutive matches. The M option 
allows yoj to change this mmber. This has two effects: 

1. Areas of the source where almost every other line has been changed will 
be reported as a single change block, rather than being broken into several 
small change blocks. 

2. Areas of the source which are entirely different are not broken into 
different change blocks because of trivial similarities (such as blank lines, 
lines with only begin or end, and so forth) 

Diff makes a second pass through the input files, to report the changes 
detected, aid to verify that matching hash codes actually represent matching 
lines. Any spurious match found during verification is reported as a 
"JACKPOT". The probability of a JACKPOT is very low, since two different 
lines must hash to the same code at a location in each file which extends the 
longest common sitosequence, aid in a matching context which is larc^ enough 
to exceed the threshold for acceptance. 

See Also 

ByteDlff 

Notes 

Diff can handle files with up to 2000 lines. 
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lis DunpGbJ 
Synopsis 

DumpObj Is a disassennbler for 68000 code. This option provides a symbolic 
and formatted listing of the contents of object files. It can disassemble 
either an entire file, or specific modules within the file. 

Dialog 

Input file? [.OBJ] 
Output file? [-CONSOLE] 

Dump A(ll, S(oine, or P(articular modules [S]? 
Dunp file positions [NJ? 
DurnJ3 selected object code [N]? 

Description 

DumpObj first asks for the input file which should be an unlinked object file. 
The output (listing) file defaults to -CXMSOLE. You are asked whether ypu 
want to dump All, some, or Particular modules. 

If you respond S, DumpObj asks you for confirmation before dumping each 
module. A response of [CLEAR] gets you back to the top level. If you 
respond P, DumpObj asks you for the particular module(s) you want dumped. 

The file position is a number of the form [0,000] where the first digit is the 
block number (decimal) within the file and the second number is the byte 
number (hexadecimal) within the block at which the module starts. This 
information can be used in conjunction with the DumpPatch program. 

If you want tre selected object cocte to be chjmped, respond Y to the final 
prompt The default for this prompt is N. 

See Also 

Dum(:#=>atch 

Notes 

DumpObj displays only the low order 24 bits of longint fields, which are 
interpreted as addresses. This is consistent with the hardware, but causes 
some bytes of the file not to be displayed. 
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11.6 CXinpPatch 
Synopsis 

Dump and/or patch a file 

Dialog 

DumpPatch - Hexadecimal Dump and Patch 

File: - Output: [-CONSOLE] [.TEXT] - 

If you want to select the default of [-CONSOLE], press [RETURN] and select 
the block number you want to start with; for example^ 2. 

If you type a file n^ne^ the following prompt appears: 

Would you like to access (Input file name) interactively? (Y or N) 

If you respond Y, you will be prompted for the block number you want to 
start with. If you respond H you will be prompted for starting and ending 
block numbers. The default values are for the starting block number and 
EOF for the ending block number. 

Description 

DumpPatch provides a textual representation of the contents of my file and 
the ability to change its contents in either the ASCII character or 
hexadecimal form. The file dump is block oriented with the hexadecimal 
representation on the left and the corresponding ASCII representation on the 
right If a byte cannot be converted to a print^le character^ a dot is 
substituted. The patch facility uses the arrow keys to move around within the 
displayed block and change the value of any byte. 

When DumpPatch is Run, you will be asked for the full name of the input file. 
No extensions are appended. Pressing [RETURN] will exit DumpPatch. If the 
input file can be found, you will be asked where you want to direct the 
output. The default for the output file is [-printer]. If you type an output 
file nane, a .TEXT extension will be added if necessary. If you type a device 
name; for exanple, -printer, no extension will be appended. 

If an output file name or a valid device name was entered, you will be asked 
if you would like to access the input file interactively. If you answer No, you 
will get a quick dump of the input file and will be prompted for the starting 
block to dump. The default [RETURN] for the last block to be dumped is the 
last block of the iqput file. If you specify a block that is beyond the 
end-of-flle, you will be given the block number of the last block in the file. 
Pressing [CLEAR] enables you to exit with no dumping. 

Once a file has been completely dumped, DumpPatch asks you for the next 
input file. Press [RETURN] to exit the program. 
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If you access the input file Interactively, you will be asked for the block to 
dump. The output will be clumped to the screen with the option of dumping it 
to the output file when you are ready to leave that block. Press the space 
bar to look at the next halfblock. Press [CLEAR] to go into patch mode. 
Press [RETURN] to quit the present block. 

When you are in patch mode, the cursor will be found in the upper left comer 
at word of the block. The arrow keys are used to move the cursor around 
in the current block ar«j to previous or successive blocks. Press [TAB] to 
toggle between the hexadecimal and the ASCII portions of the display. A 
chmge made on one sicte of the display is automatically updated on the other 
side as well. Until you get ready to move out of the current block you may 
undo any chaai^s by pressing [CLEAR]. When leaving a block in which you 
made changes, you will be asked if ycii want to write the chcnged block back 
to the input file. This is your last chance to undo any unwanted changes! If 
you specified output to something other than the console, you will also be 
asked if you want to dump the current block to the output file when you try 
to leave that block. To exit patch mode press [RETURN]. 

See Also 

DumpCX)j 
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11.7 FlleDlv and FlleJoin 
Synopsis 

FileDiv can be used to break a large file Into several smaller pieces. FlleJoIn 
can then be used to rejoin these pieces into one file. These functions are 
most useful when saving and restoring very large files^ or when you want to 
break a large text file into smaller ones to be viewed in the Editor. 

Dialog 

Is this a .TEXT file? (Y or N) 

Infile name : [.text] 
(Xitf lie name : [.text] 

You might want to keep portions of a file on more than one disk. To give 
you an opportunity to do that, FileDiv contains the following additional 
prompts: 

Another disk? (Y or N) 

Have you inserted the next disk? (Y or N) 

Description 

Do not include the suffix in the file name. If, for exaiiple, you want to 
divide TEMP.TEXL give TEMP as the input file, and TEMP (or whatever) as 
the output file. FileDiv will create a group of files named TEMP.LTEXt, 
TEMP.2.TEXT, and so on, until TEMP.TEXT is completely divided up. 

To rejoin the pieces of the file. Run FlleJoin. The dialog is the same as for 
FlleDlv. 
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11-8 Find 

Synopsis 

Find searches a text file for a pattern. 

Dialog 

type ".?" to display or change options 
Enter input file name [.TEXT] (name of the file to >o& searched) 
Enter output file name [-CONSOLEJ/[.TEXT] (default is the console) 
Enter pattern: Ooattem to tie matched) 

Description 

Find searches text files for lines which match a string pattern. Lines found 
are printed to the console. The following options are recognized: 

+C Matches are case sensitive 

+s Matches are space sensitive. 

+D Print dots as lines which do not match are scanned. 

+L As lines are reported^ print out the relative line numbers. 

+T Report the files that are being scanned. 

Typing ? in response to any of the input prompts will display a description of 
the options available and read in the options. You can leave Find by typing 
[RETURN] or [CLEAR] in response to the input or pattern prompts. 

More than one file can be input at a time. Find supports the same wildcard 
scheme as the Workshop File Manager. So submitting "-paraport-ch-" will 
direct Find to search all of the text files beginning with "ch" on the paraport 
directory. Find can also search prectefir«d lists of files; su|:^ose the file 
"foobar.text" contained: 

" hoohatext 
grok.text 
bruhahatext" 

Then submitting "<foobar.text" will direct Find to search^ sequentially^ 
"hoohatext**^ "grok.text'V and then "bruhahatext". If you type "foobar.text" 
(without the leading '<') then Find will search "foobar.text"^ not the files listed 
therein^ for the pattern. 

Notes 

Find truncates output lines to 256 characters. 
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11.9 GXRef 
Synopsis 

Global Cross Reference. 

Dialog 

Input file [.OBJ] ? 

Listing file [CONSOLE: ]/[. TEXT) - 

Description 

GXRef lists all the modules which call a given procedure, and all the modules 
which that procedure calls. It provides a global cross reference of subroutines 
and modules. 

GXRef accepts any number of object file as infxit. When you have entered all 
the object files, press [RETURN] in response to the input file request. 
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ILIO PortConflg 
Synopsis 

PortConflg enables you tx) configure the RS232 ports. 

Dialog 

First you must supply information on how to configjre the port. 

Which RS232 port do you want to configure ? (A or B) 

What parity setting ? 

0) No parity 

1) Odd parity; no in|xit parity checking 

2) Odd parity; input parity errors -^ 00 

3) Even parity; no input parity checking 

4) Even parity; input parity errors - $80 
Enter selection (o - 4) [0] 

What output handshake protocol ? 

0) None 

1) DTR handshake 

2) XQN/XOFF handshake 

3) Delay after CRJ_F 
Enter selection (0 - 3) [0] 

What baud rate ? [9600] 

Receive and buffer Irqxit how ? 

0) Buffer input until full request is satisfied 

1) Return whatever is received 
Enter selection (0 - l) [l] 

What input handshake protocol ? 

0) None 

1) DTR handshake 

2) XON/XCFF handshake 
Enter selection (0 - 2) [0] 

Adjust type-ahead buffer how ? 

0) Flush only 

1) Flush and re-size 

2) Flush^ re-size, and set thresholds 
Enter selection (0 - 2) [0] 

What form of disconnect detection ? 

0) None 

1) BREAK detected means disconnect 
Enter selection (0 - 1) [0] 

Timeout on output after how many seconds (0 - no timeout) ? [OJ 
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Automatic linefeed insertion ? 

0) Disabled 

1) Enabled 

Enter selection (0 - 1) [0] 

We are now ready to configure the port. Shall we proceed? (Y or N) 

PortConfig contains a series of questions. After you answer one, you will be 
prompted for an answer to the next one. The default values for each question 
are shown in brackets. 

Description 

With the PortConfig utility^ you can configure the RS232 ports, and establish 
such things as the parity setting, handshake protocol, baud rate, disconnect 
detection, and so forth. If you are using Pascal and want additional 
information on port configuration, see Section 2.10.12 in Ofxrating System 
Reference l^lanuai for the Lisa. 

NOTE 

For Serial A and Serial B ports, the baud rate can be set to 50, 75, 
110, 150, 200, 300, 600, 1200, 1800, 2000, or 2400. Serial A can also be 
set to 4800 or 9600. 

For output only. Serial B can also be set to 3600, 4800, 7200, %00, or 
19200. 
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11.11 SegMap 
Synopsis 

SegMap produces a segment map of one or more object files. 

Dialog 

Files to Map ? [.OBJ] 
Listing File ? [-CONSOLE] 

Description 

SegMap accepts either an object file name or a command file name^ which 
enables you to include predefined lists of files. 

A command file must be preceded with a "<". SegMap adds the .TEXT suffix 
to the command file name. 

For example, if the file "Applctext" contains: 

"code" 

"pascal" 

"basic" 

Submitting "<Apple" directs SegMap to accept sequentially, "code.obj", 
"pascaLobf, and "basicobj". 

The map information includes the object file name, the name of the unit in 
the file, the names of the segments used in that unit (if any), and the new 
segment names. 
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11.12 SXRef 
Synopsis 

Pascal cross reference utility 

Dialog 

Source File ? [.TEXT] 

Output file for Listing ? [-CrossRef] [.TEXT] 

Do you want a numbered listing of tne source ? (Y or N) 

Flag the declarations and assignments of each indentifier ? (Y or N) 

Declaration Character ? [*] 

Assignment Character ? [-] 

Text file of words to Omit ? [SXRef.Omit] [.TEXT] 

Description 

SXRef gives a numbered listing of the source files and an alphabetical listing 
of identifiers found. For each identifier, all references to the identifier are 
listed in the order in which the references were encountered. Procedure and 
Function names along with all references to them will be found at the end of 
the cross reference listing. 

Identifiers follow cunent Lisa Pascal conventions: the first eight characters, 
without regard to case sensistivity. Case insensitivity is achieved by shifting 
identifiers to lower case, within the Cross Reference sectioa 

INCLUDE files are automatically processed. User interfaces are not 
processed. Comments and strings are recognized and skipped. There is no 
conditional compilation processing or elimination of code controlled by 
b(X)ledn constaits. 

SXRef will accept multiple source files. This can be used to get a cross 
reference of a set of Main Programs together with the Units which the 
programs use. Refererx^s are given by file nwnber and line number within 
the file. A directory of files read is printed at the end of the source listing, 
and before the cross refererx:e section. 

SXRef attempts to read a file for a list of words to omit from the cross 
reference. The default name is SXRef.omittext, but other names can be 
given. If the file cannot be opened, execution proceeds normally without 
omitting any identifiers. 

SXRef will optionally flag where all Identifiers are declared aid assigned 
values. The default flag characters are: [*] for declaration and [-] for 
assignment 

If SXRef runs short of storage, an error message Is given and the program 
aborts. 

See Also 

GXRef, UXRef 
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11.13 UXRef 
Synopsis 

Show unit dependencies of one or more Pascal source programs 

Dialog 

Type "?" to see current options 

Source File ? [.TEXT] 

Output file for Listing ? [-Cross Ref] [.TEXT] 

Text File of unit names with unexpected pathnames ? [UXRef.UMap] [.TEXT] 

Description 

UXRef gives an alphabetical listing of programs and units. Each program or 
unit listed includes two parts: 1) alphabetically lists all programs and units 
that USE that program or unit, and 2) alphabetically lists all units that ARE 
USED BY that program or unit 

UXRef recognizes conditional compilation and will determine the truth value 
of any {$ifc ...} expressioa Compile-time variables can be of both boolean 
aid integer types and a {$setc ...} can change a variable to a new type. 
Warnings will be sent to the console if a syntactical or semantic error is 
fomd in an {$ifc ...} expressioa 

Warnings about units that can't be found are sent to the console. Even though 
a unit cannot be found it will still show up on the Cross Reference listing. 

Options may be turned on or off during file name prompt stage of UXRef. 
Four options are included: 

*C You will be asked to maiually clarify a ccwmpile-time expression 
or variable that camot be evaluated conectly. Enter "T* for 
true SBTd *F' for false. If this option is off^ the entire expression 
will be treated as false. 

+F As each file is opened^ a message will be printed on the 

-console specifying the file name and the unit name being read. 

♦I "Include Files" will be treated as units and will show up on the 
Cross Reference listing, only those "include files" that are 
found between the beginning of the program/unit and the end of 
the uses section will be listed. 

+W All warnings will be written at the beginning of the Cross 
Reference listing as well as on the console. 

By entering ? during the file name prompt stage a short description of each 
option will appear along with their current values. The default values of the 
options are: -C^ ♦F, -\, and -W. 

UXRef provides a facility to map a unit to an unexpected pathname. For 
example, the unit "FOO" might not be compiled yet (e.g., "FoaCBJ" does not 
exist) and the source is named "UNIT/FOO.TEXT'. UXRef will attempt to read 
a file for a list of logically connected units and pathnames and if 
FOO,-UPPER-UNlT/F0aTEXT is an entry in that file then "UNlT/FOaTEXT" 



11-18 



Workshop User's Guide The Utilities 

will be located and searched on the UPPER diskette when the unit FOO is 
referenced. The unit name and the pathname must be separated by a comma 
with no extra spaces between. In addition this same facility can be used to 
shut off unnecessary warnings that occur when an inaccessable unit is 
referenced. Normally warnings will be printed when a unit cannot be founds 
but If the unit name followed by a comma appears on UXRef.OmitTEXT (or 
some other name provided by the user) the warnings for that unit will be 
bypassed. Example entries are: 

F00,-UPPER-UN1T/F00.TEXT 

SYSCALL 

See Also 

GXRef, SXRef 
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A.1 Assembler Errors A-i 

A.2 Linker Erron A-3 

A.3 Messages Generated by ObjIOLib , A-6 

A.4 Operating System Errors A-7 



Error Messages 



A.1 Assembler Errors 

The following enors can be produced by the Assembler. 

1 Undefined label 

2 Operand out of range 

3 Must have procedure name 

4 Number of parameters expected 

5 Extra garbage on line 

6 Input line over 80 characters 

7 Not enough .IPs 

8 Illegal use of .REF label 

9 Identifier previously declared 

10 Improper format 

11 .EQU expected 

12 Must £QU before use if not to a label 

13 Macro identifier expected 

14 Word addressed machine 

15 Backward .ORG currently not allowed 

16 Identifier expected 

17 Constant expected 

18 Invalid structure 

19 Extra special symbol 

20 Branch too far 

21 Variable not PC relative 

22 Unexpected .ENDM 

23 Not enough macro parameters 

24 Operand not absolute 

25 Illegal use of special symbols 

26 Ill-formed expression 

27 Not enough operands 

28 Too mctfiy undefined lables in this expression 

29 Constant overflow 

50 Illegal decimal constant 
31 Illegal octal constant 

52 Illegal binary constant 

53 Invalid key word 

54 Macro stack overflow - 5 nested limit 

55 Include files cannot be nested 

56 Unexpected end of iiput 

57 This is a bad place for an .INCLUDE file 

58 Only labels and comments may occupy col 1 

59 Expected local label 

40 Local label stack overflow 
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41 Siring constant must be on one line 

42 string constant exceeds 80 characters 

43 Illegal use of macro parameter 

44 Illegal use of .DEF label 

45 Expected key word 

46 siring expected 

47 Nested macro definitions illegal 
zi^ •-.' or *<>• expected 

49 Cannot .EQU to undefined labels 

50 Not even a register 

51 Not a Data Register 

52 Not an Address Register 

53 Register expected 

54 Right paren expected 

55 Right paren or comma expected 

56 Unrecognizable operand 

57 Odd location counter 

58 Comma expected 

59 One operand must be a Data Register 

60 DnjDn or -(An),-(An) expected 

61 No longs allowed 

62 First operand must be immediate 

63 Flnl operand must be Dn or #E 

64 (An*)XAn*) expected 

65 Second operand must be an An 

66 Second ojDerand must be a Dn 

67 #<data>X)n expected 

68 First operand nnusi be a Dn 

69 An^#<displacement> expected 

70 An is not allowed with byte 

71 Only alterable addressing nrxxles allowed 

72 Only data alterable addr modes allowed 

73 An is not allowed 

74 USP, SR, and CCR not allowed 

75 Cannot move from CCR 

76 Dx^Ay) or d(Ay);Dx expected 

77 Only memory alterable addr modes allowed 

78 Only control addressing modes allowed 

79 Must branch backwards to label 

80 Patch out of code buffer boundaries 

81 Code buffer overflow 

82 Segment name must be in a string 

83 Cannot .DEF macro 

84 MACRO defined already 

85 Illegal use of MACRO 

86 ERROR while WRITING SYMBOL TABLE FILE 

87 Not enough ENDCs 
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88 Must have an <EA> (effective address) 

89 Unimplemented Motorola directive 

90 Operand size must be a word 

91 No undefined or forward label in .BLOCK 

92 Only byte-size displacement value allowed 
A.2 Linker Errors 

Linker errors are either Warnings^ Errors, or Fatal Errors. All Linker errors 
are listed below, along with a brief description of their probable cause. The 
Linker can also produce erron from ObjIOLib. These erron are listed in 
Section A.3. 

A.2.1 Warnings 

A warning message is an indication of a potential error. However, the link is 
allowed to continue normally and may produce a valid output file. Warnings 
cannot be ignored! You must make sure that the conditions indicated by the 
warning are what was intended. When in doubt, atterrpt to remedy the 
conditions which caused the warning message to occur. 
No Starting Location: 

The file containing the main Pascal program has probably been omitted. 
Duplicate entry definitions: 

An entry name has been found in a library file which is the same as a 
name in the main program. References to the name are interpreted as 
referring to the main program entry. (NOTE: this can be an error if a Unit 
In the link was trying to reference the library entry.) 

ConfUct with Intrinsic unit Name: 

A regular Unit in the link has the ssfftie name as a library Intrinsic Unit. 

Also an lU segment: 

A segement In the link has the same name as as a library segment. 

K12. Errors 

A error message is an indication of a condition which prevents the production 
of a valid output file. The link is allowed to continue, in order to detect any 
other errors. However, the output file will not be produced. 

Multiple start locations. 

More than one main program file has been provided as input to the Linker. 

Duplicate definition of unit Name 
Doubly dedned Global Data area: 

Two units of the same name have been provided as input to the Linker. 
Duplicate entry definitions. 

Two entries of the same name have been found in the Linker input files. 
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undefined entry. 

The entry name has been referenced, but not defined. Either an input file 
has been omitted or a spelling error was made in a procedure name. 

undefined code Module: 

The module name has been referenced^ but not defined. Either an input 
file has been omitted or a spelling error was made in a procedure name. 

undefined data area: 

The unit name has been referenced^ but not defined. Either an input file 
has been omitted or a spelling enor was made in a unit nama 

Segment name not found in Intrinsiolib: 

A name which occurs in an intrinsic library file does not appear in the 
directory file. Probably indicates an "architecture" consistency error; that 
is, the library file was not linked against the same directory as the current 
directory. 

Bad block in Library file. 

The library file being read does not have valid contents. 

Relocation Block. 
Common Definition Block. 

The lULinker does not support these object blocks. Either the object file 
Is very old, or an error has occured in the object file format. 

Bad block, start of file: 
Bad block type 

The object file does not have valid contents. Most likely a disk error has 
caused to object file to be damaged. You should regenerate the object 
file or obtain a copy from a backup disk. 

Bad Module type: 

This indicates an Internal Linker error, or perhaps an undetected memory 
error. 

lU Code with main program. 

The input contains both unlinked intrinsic units and an unlinked main 
program. Link the Intrinsic units into a library file. Then link the main 
program, using the Intrinsic library as Input 

More than 32K of globals 

The globals required by the main program and regular units exceeds the 
current limitation of 32K You will need to recompile the program or Vtb 
units, rroving some large variables to the heap. 

Code Size too big: 

The code in the segment being linked exceeds the current limitation of 
32K You will need to resegment the program either using the +M Linker 
option, or by recompiling with different $S compiler options. 
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Segs 1-16 are Reseivecb 

The directory indicates that a segment name has been associated with one 
of the segments reserved for physical addresses. 

A^.3 Fatal Enon 

A fatal error Indicates a condition which prevents the link from continuing. 
Linker error - 

Indicates an enor In internal Linker logic^ perhaps caused by an 

undetected disk or memory error. 

Inconsistent intnnsicJlb. 

Prob^ly indicates smti I/O error^ such as bad media^ which has corrupted the 
directory file^ or the specification of a bad directory. 

Cant re-open inFlle: xxxxxxx 

An I/O error has occured which prevents the opening of file 'xxxxxxx* for 
phase 2 processing. Examine the file using the File Manager^ or 
regenerate the file. Then attempt to do the link agaia 

Too many code segments. 

The program has too many small segments. The current limitation Is for 
segments numbered 17 through 105. Reduce the number of segments by 
combining small segments with the *M option in the Linker. 

Regular unit during Intrinsic Link. 
Intrinsic unit during Regular Link. 
MainProg as part of Intrinsic Library Link: 

The Linker has detected an unlinked regular unit or main program mixed 
with unlinked intrinsic units. 

Regular unit in Intrinsic Seg File: 

The Linker has detected an unlinked regular unit in an intrinsic library 
file. 

Not Main or Intrinsic Link: 

The Linker has not seen a valid input file to decide what type of link Is 
desired. 

No Starting locatioa linking Main Program: 

The file containing the Pascal main program has been omitted from the 
input list^ or is damaged. 

One or more lU Segs not in IntrinsioLib: 

An intrinsic segment name does not appear In the directory flla Probably 
indicates an architecture consistency error; that Is, the library file was not 
linked against the same directory as the current directory. 

Bad umt Block (Old iBJ file?> 

Either this is a very old object file, not supported by this Linker, or a disk 
error has occured. 
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A.3 Messages Generated by QbjIGLib 

The lULinker uses a number of units from the ObjIOLib intrinsic library file. 
These units are also used by the Compiler, Code Generator, and object file 
utility programs. These units detect some error conditions and issue messages. 

A.3wl warnings 

No Code Block fdund in input J_IB fil& 

For the as. Loader, there should be a Code Block in the directory file. 
Perhaps this is an old directory file, or a directory for another operating 
system. 

Errors detected: No Output J_IB file writtea 

When the error count is nonzero, the directory file is not rewritten. 

A.3-2 Erron 
Bad Peek 
BadPeek2: 

Indicates an internal error in the ObjIOLib library, perhaps caused by a disk 
or memory error. Check your hardware then retry the link. 

I/O error, can't write last bufffen 

Either the volume does not have enough space for the file or a hardware 
error has occurred. 

MemMan Erron 

An error has occuned in the managing of storage elements. Usually this 
error is due to insufficient initial space (Allocation error) or due to 
exhaustion of available space (Memory Full). The cause of the error is 
indicated on the next output line. 

Attempt to delete vertex with arcs. 
Argument to OppositeVertex is not an endpoint: 

These are errors reported by the Graphs unit If they occur while the 
Linker is executing, there has been an internal logic error, perhaps caused 
by an undetected I/O or memory enor. 

A33 Fatal Errors 
I/D error. 

An I/O error has occurred within FilelQ Usually this is the result of a 
volume being almost full or a hardware failure. The previous message line 
indicates whether the error occurred during reading or writing and at what 
position within the file the error occurred. 

No VersionControl Block. 
No unit Tabl& 
No Segment Table. 
No File Names Table: 

Indicates a bad format for the directory file. The indicated block is 

missing from the directory, but is required. 
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Errors during Installation: 

Indicates errors during the Installation of an object file library. 

SetCbJInvan VarSize is not divisible by variant size: 

Indicates an Internal logic error In Objia Either Initialization was not 
called^ or ObJIO globals have been clobbered. 

File Buffer less than 2 blocks: 

Indicates an internal logic enor in Fileia Perhaps initialization was not 
called. 

Attempt to delete item not on list: 

This is an error reported Xy^^ the Lisats unit. If it occurs while the Linker 
is executing^ there has been an internal logic error, perhaps caused by ai 
undetected I/O or memory error. 

A.4 Operating System Erron 

-6081 End of exec file input 

-6004 Attempt to reset text file with typed-file type 

-6003 Attempt to reset nontext file with text type 

-1885 ProFile not present during driver Initialization 

-1882 ProFile not present during driver initialization 

-1176 Data in the object have been altered by Scavenger 

-1175 File or volume was scavenged 

-1174 File was left open or volume was left mounted, and system crashed 

-1173 File was last closed by the OS 

-1146 Only a portion of the space requested was allocated 

-1063 Attempt to mount boot volume from another Lisa or not most recent 
boot volime 

-1060 Attempt to mount a foreign boot disk following a temporary unmount 

-1059 The bad block directory of the diskette Is almost full or difficult to 

read 
-6% Printer out of paper during Initialization 
-660 Cable disconnected during ProFile initialization 
-626 Scavenger indicated data are questionable, but may be OK 
-622 Parameter memory and the disk copy were both Invalid 
-621 Parameter memory was Invalid but the disk copy was valid 
-620 Parameter memory was valid but the disk copy was invalid 
-413 Event channel was scavenged 
-412 Event channel was left open and system crashed 
-321 Data segment open when the system crashed. Data possibly Invalid. 
-320 Could not determine size of data segment 
-150 Process was created, but a library used by program has been scavenged 

and altered 
-149 Process was created, but the specified program file has been scavenged 

and altered 
-125 Sepcifled process Is already terminating 
-120 Specified process is already active 
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-115 Specified process Is already suspended 

100 Specified process does not exist 

101 Specified process is a system process 
110 Invalid priority specified (must be 1..225) 

130 Could not open program file 

131 File system error while trying to read program file 

132 Invalid program file (Incorrect format) 

133 Could not get a stack segment for new process 

134 Could not get a syslocal segment for new process 

135 Could not get sysglobal space for new process 

136 Could not set up communication channel for new process 
138 Error accessing program file while loading 

141 Error accessing a lIDrary file while loading program 

142 Cannot run protected file on this machine 

143 Program uses an Intrinsic unit not found In the Intrinsic Library 

144 Program uses an intrinsic unit whose name/type does not agree with 
the intrinsic Library 

145 Program uses a shared segment not found in the Intrinsic Library 

146 Program uses a shared segment whose name does not agree with the 
Intrinsic Library 

147 No space in syslocal for program file descriptor during process creation 

148 No space in the shared lu data segment for the program's shared lu 
globals 

190 No space in syslocal for program file description during List_LibFiles 
operation 

191 Could not open program file 

192 Error trying to read program file 

193 Cannot read protected program file 

194 Invalid program file (incorrect format) 

195 Program uses a shared segment not found in the Intrinsic Library 

196 Program uses a shared segment whose name does not agree with the 
Intrinsic Library 

198 Disk I/O error trying to read the Intrinsic unit directory 

199 Specified library file number does not exist in the Intrinsic Library 

201 No such exception name declared 

202 No space left in the system data area for Declare_Excep_Hdl or 
Signal_Excep 

203 Null name specified as exception name 

302 Invalid LDSN 

303 No data segment bound to the LDSN 

304 Data segment already bound to the LDSN 

306 Data segment too large 

307 Input data segment path name Is invalid 

308 Data segrrent already exists 

309 Insufficient disk space for data segment 

310 An invalid size has been specified 

311 Insufficient system resources 
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312 Unexpected File System error 

313 Data segment not found 

314 Invalid address passed to lnfo_Address 

315 Insufficient memory for operation 

317 Disk error while trying to swap in data segment 

401 Invalid event channel name passed to MaKe_Event_Chn 

402 No space left in system global data area for Open_Event_Chn 

403 No space left in system local data area for Open_Event_Chn 

404 Non-block-structured device specified in pathname 

405 Catalog is full in Make_Event_Chn or Open_Event Chi 

406 No such event channel exists in Klll_Event_Chn 

410 Attempt to qaen a local event channel to send 

411 Attempt to ojjen event channel to receive when event channel has a 
receiver 

413 Unexpected File System error in open_Event_Chn 

416 Cannot get enough disk space for event channel in qpen_Event_Chn 

417 Unexpected File System error in close_Event_Chn 

420 Attempt to wait on a channel that the calling process did not open 

421 wait_Event_Chn returns empty because sender process could not 
complete 

422 Attempt to call Walt_Event_Chn on an empty event-call channel 

423 Cannot find corresponding event channel after being blocked 

424 Amount of data returned while reading from event channel not of 
expected size 

425 Event channel empty after being unblocked, Wait_Event_Chn 

426 Bad request pointer error returned in Wait_Event_Chn 

427 wait^Llst has illegal length specified 

428 Receiver unblocked because last sender closed 

429 Unexpected File System error in Wait_Event_Chn 

430 Attempt to send to a channel which the calling process does not have 
open 

431 Amount of data transfened while writing to event channel not of 
expected size 

432 Sender unblocked because receiver closed in Send_Event_Chn 

433 Unexpected File System error in Send_Event_Chn 

440 Unexpected File System error in Make_Event_Chn 

441 Event channel already exists in Make_Event_Chn 
445 Unexpected File System error in Kill Event_Chn 
450 Unexpected File System error in Flush_Event_Chn 

530 size of stack expansion request exceeds limit specified for program 

531 Cannot perform explicit stack expansion due to lack of memory 

532 Insufficient disk space for explicit stack expansion 
600 Attempt to perform I/O operation on non I/O request 
602 No more alarms available during driver Initialization 

605 Call to nonconflgured device driver 

606 Cannot find sector on floppy diskette (disk unformatted) 
608 Illegal length or disk address for transfer 
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609 Call to nonconflgured device driver 

610 No more room in sysglobal for I/O request 

613 Unpermitted direct access to spare track with sparing enabled on 
floppy drive 

614 No disk present in drive 

615 wrong call version to floppy drive 

616 Unpermitted floppy drive function 

617 Checksum error on floppy diskette 

618 Cannot formats or write protected^ or error unclamping floppy diskette 

619 No more room in sysglobal for I/O request 

623 Illegal device control parameters to floppy drive 

625 Scavenger indicated data are bad 

630 The time passed to Delay_Time, Convert_Time^ or send_Event_Chn has 
invalid year 

631 Illegal timeout request parameter 

632 No memory available to initialize clock 

634 Illegal timed event id of -i 

635 Process got unblocked prematurely due to process termination 

636 Timer request did not complete successfully 

638 Time passed to Delay_Time or Send_Event_Chn more than 23 days from 
current time 

639 Illegal date passed to Set_Time^ or illegal date from system clock in 
Get_Tlme 

640 RS-232 driver called with wrong version number 

641 RS-232 read or write Initiated with Illegal parameter 

642 Unimplemented or unsupported RS-232 driver function 

646 No memory available to initialize RS-232 

647 Unexpected RS-232 timer interrupt 

648 Unpermitted RS-232 Initialization, or disconnect detected 

649 Illegal device control paraT\eters to RS-232 

652 N-port driver not Initialized prior to ProFile 

653 No room in sysglobal to initialize ProFile 

654 Hard error status returned from drive 

655 Wrong call version to ProFile 

656 Unpermitted ProFile function 

657 Illegal device control parameter to ProFile 

658 Premature end of file when reading from driver 

659 Corrupt File System header chain found in driver 

660 Cable disconnected 

662 Parity error while sending command or writing data to ProFile 

663 Checksum error or CRC error or parity error in data read 
666 Timeout 

670 Bad command response from drive 

671 Illegal length specified (must - 1 on Input) 

672 Unimplemented console driver function 

673 No memory available to initialize console 

674 Console driver called with wrong version number 
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675 Illegal device control 

680 Wrong call version to serial driver 

682 Unpermitted serial driver function 

683 No room in sysglobal to initialize serial driver 

685 Eject not allowed this device 

686 No room in sysglobal to initialize n-port card driver 

687 Unpermitted n-port card driver function 

688 Wrong call version to n-port card driver 

690 Wrong call version to parallel printer 

691 Illegal parallel printer parameters 

692 N-port card not initialized prior to parallel printer 

693 No room in sysglobal to initialize parallel printer 

694 Unimplemented parallel printer function 

695 Illegal device control parameters (parallel printer) 

696 Printer out of paper 

698 Printer offline 

699 No response from printer 

700 Mismatch between loader version number and Operating System version 
number 

701 OS exhausted its internal space during startup 

702 Cannot make system process 

703 Cannot kill pseudo-outer process 

704 Cannot create driver 

706 Cannot initialize floppy disk driver 

707 Cannot initialize the File System volume 

708 Hard disk mount table unreadable 

709 Cannot map screen data 

710 Too many slot-based devices 

724 The boot tracks do not know the right File System version 

725 Either damaged File System or dannaged contents 

726 Boot device read failed 

727 The OS will not fit into the available memory 

728 SYSTEM.OS is missing 

729 SYSTEM.C0NF1G is corrupt 

730 SYSTEM.OS is corrupt 

731 SYSTEM.DEBUG or SYSTEKDEBUG2 is corrupt 

732 SYSTEM.LLD is corrupt 
735 Loader range error 

734 Wrong driver is found. For instance^ storing a diskette loader on a 
ProFile 

735 SYSTEM.LLD is mlsslng 

736 SYSTEM.UNPACK is missing 

737 unpack of SYSTEKOS With SYSTEM.UNPACK failed 

801 lOResuit <> on I/O using the Monitor 

802 Asynchronous I/O request not completed successfully 

803 Bad combination of mode parameten 
806 Page specified is out of range 
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809 Invalid arguments (page^ address^ offset or count) 

810 The requested page could not be read In 

816 Not enough sysglobal space for File System duffers 

819 Bad device number 

820 No space In sysglobal for asynchronous request list 

821 Already initialized I/O for this device 

822 Bad device number 

825 Error in parameter values (Allocate) 

826 No more room to allocate pages on device 

828 Error in parameter values (Deallocate) 

829 Partial deallocation only (ran Into unallocated region) 
835 Invalid s-file number 

837 Unallocated s-flle or I/O error 

838 Map overflow: s-file too large 

839 Attennpt to compact file past peof 
841 Unallocated s-file or I/O error 

843 Requested exact fit, but one could not be provided 

847 Requested transfer count is <- 

848 End of file encountered 

849 Invalid page or offset value in parameter list 
852 Bad unit number 

854 No free slots in s-list directory (too many s-files) 

855 No available disk space for file hints 

856 Device not mounted 

857 Empty, locked, or invalid s-flle 

861 Relative page is beyond PEOF (bad parameter value) 

864 No sysglobal space for volume bitmap 

866 Wrong FS version or not a valid Lisa FS volume 

867 Bad unit number 

868 Bad unit number 

869 Unit already mounted (mount)/no unit mounted 

870 No sysglobal space for DCS or MDDF 

871 Parameter not a valid s-file ID 

872 No sysglobal space for s-file control block 

873 Specified file is already open for private access 

874 Device not mounted 

875 Invalid s-file ID or s-file control block 
879 Attempt to postion past LEOF 

881 Attempt to read empty file 

882 No space on volume for new data page of file 

883 Attempt to read past LEOF 

884 Not first auto-allocation, but file was empty 

885 Could not update fllesize hints after a write 

886 No syslocal space for I/O request list 

887 Catalog pointer does not indicate a catalog (bad parameter) 

888 Entry not found in catalog 

890 Entry by that name already exists 
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891 Catalog is full or is damaged 

892 Illegal name for an entry 

894 Entry not found, or catalog is damaged 

895 Invalid entry name 

896 Safety switch is on—cannot kill entry 

897 Invalid bootdev value 

899 Attempt to allocate a pipe 

900 Invalid page count or FCB pointer argument 

901 Could not satisfy allocation request 

921 Pathname invalid or no such device 

922 Invalid label size 

926 Pathname invalid or no such device 

927 Invalid label size 

941 Pathname invalid or no such device 

944 Object is not a file 

945 File is not in the killed state 

946 Pathname Invalid or no such device 

947 Not enough space in syslocal for File System refdb 

948 Entry not found in specified catalog 

949 Private access not allowed if file already open shared 

950 Pipe already in use, requested access not possible or dwrite not allowed 

951 File is already opened in private nriode 

952 Bad refnum 

954 Bad refnum 

955 Read access not allowed to specified object 

956 Attempt to position FMARK past LEOF not allowed 

957 Negative request count is Illegal 

958 Nonsequential access is not allowed 

959 System resources exhausted 

960 Error writing to pipe while an unsatisfied read was pending 
%l Bad refnum 

%2 No WRITE or APPEND access allowed 

%3 Attempt to position FMARK too far past LECF 

%4 Append access not allowed in absolute mode 

965 ApiDend access not allowed in relative mode 

966 Internal inconsistency of FMARK and LECF (warning) 

967 Nonsequential access is not allowed 

968 Bad refnum 

971 Pathname Invalid or no such device 

972 Entry not found in specified catalog 
974 Bad refnum 

977 Bad refnum 

978 Page count is nonpositive 

979 Not a block-structured device 

981 Bad refnum 

982 No space has been allocated for specified file 

983 Not a block-structured device 
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985 Bad refnum 

986 No space has been allocated for specified file 

987 Not a block-structured device 

988 Bad refnum 

989 Caller is not a reader of the pipe 

990 Not a block-structured device 

994 Invalid refnum 

995 Not a block-structured device 

999 Asynchronous read was unblocked before it was satisfied 

1021 Pathname invalid or no such entry 

1022 No such entry found 

1023 Invalid newname^ check for '-' in string 

1024 New name already exists in catalog 

1031 Pathname Invalid or no such entry 

1032 Invalid transfer count 

1033 No such entry found 

1041 Pathname invalid or no such entry 

1042 Invalid transfer count 

1043 No such entry found 

1051 No device or volume by that name 

1052 A volume is already mounted on device 

1053 Attempt to mount temporarily unmounted boot volume Just unmounted 
from this Lisa 

1054 The bad block directory of the diskette is invalid 

1061 No device or volume by that name 

1062 No volume is mounted on device 

1071 Not a valid or mounted volume for working directory 

1091 Pathname invalid or no such entry 

1092 No such entry found 
1101 Invalid device name 

1121 Invalid device, not mounted, or catalog Is damaged 

1128 Invalid pathname, device, or volume not mounted 

1130 File Is protected; cannot open due to protection violation 

1131 No device or volume by that name 

1132 No volume is mounted on that device 

1133 No more open files in the file list of that device 

1134 Cannot find space In sysglobal for open file list 

1135 Cannot find the open file entry to modify 

1136 Boot volume not mounted 

1137 Boot volume already unmounted 

1138 Caller cannot have higher priority than system processes when calling 
ubd 

1141 Boot volume was not unmounted when calling rbd 

1142 Some other volume still mounted on the boot device when calling rbd 

1143 No sysglobal space for MDDF to do rbd 

1144 Attempt to remount volume which is not the temporarily unmounted 
boot volume 
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1145 No sysglobal space for bit map to do rbd 

1158 Track-by-track copy buffer is too small 

1159 Shutdown requested while boot volume was unmounted 

1160 Destination device too small for track-by- track copy 

1161 Invalid final shutdown mode 

1162 Power is already off 

1163 Illegal command 

1164 Device is not a diskette device 

1165 No volume is mounted on the device 

1166 A valid volume is already mounted on the device 

1167 Not a block-structured device 

1168 Device name is invalid 

1169 Could not access device before initialization using default device 
parameters 

1170 Could not mount volume after Initialization 

1171 '-' is not allowed in a volume name 

1172 No space available to initialize a bitmap for the volume 

1176 Cannot read from a pipe more than half of its allocated physical size 

1177 Cannot cancel a read request for a pipe 

1178 Process waiting for pipe data got unblocked because last pipe writer 
closed it 

1180 Cannot write to a pipe more than half of its allocated physical size 

1181 No system space left for request block for pipe 

1182 Writer process to a pipe got unblocked before the request was satisfied 

1183 Cannot cancel a write request for a pipe 

1184 Process waiting for pipe space got unblocked because the reader closed 
the pipe 

1186 Cannot allocate space to a pipe while it has data wrapped around 

1188 Cannot compact a pipe while it has data wrapped around 

1190 Attempt to access a page that is not allocated to the pipe 

1191 Bad parameter 

1193 Premature end of file encountered 

1196 Sonnething is still open on device—cannot unmount 

1197 Volume is not formatted or cannot be read 

1198 Negative request count is illegal 

1199 Function or procedure is not yet Implemented 

1200 Illegal volume parameter 

1201 Blank file parameter 

1202 Error writing destination file 

1203 Invalid UCSD directory 

1204 File not found 

1210 Boot track program not executable 

1211 Boot track program too big 

1212 Error reading boot trask program 

1213 Error writing boot track program 

1214 Boot track program file not found 

1215 Cannot write boot tracks on that device 
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1216 Could not create/close internal buffer 

1217 Boot track program has too many code segments 

1218 Could not find configuration information entry 

1219 Could not get enough working space 

1220 Premature EOF in boot track program 

1221 Position out of range 

1222 No device at that position 

1225 Scavenger has detected an internal inconsistency symptomatic of a 
software bug 

1226 Invalid device name 

1227 Device is not block structured 

1228 Illegal attempt to scavenge the boot volume 

1229 Cannot read consistently from the volume 

1250 Cannot write consistently to the volume 

1251 Cannot allocate space (Heap segment) 

1252 Cannot allocate space (Map segment) 
1255 Cannot allocate space (SFDB segment) 
1257 Error rebuilding the volume root directory 

1240 Illegal attempt to scavenge a non-OS-formatted volume 

1296 Bad string argument has been passed 

1297 Entry name for the object is Invalid (on the volume) 

1298 S-list entry for the object Is invalid (on the volume) 
1807 No disk In floppy drive 

1820 Write-protect error on floppy drive 

1822 Unable to clamp floppy drive 

1824 Flof^y drive write error 

1882 Bad response from ProFile 

1885 ProFile timeout error 

1998 Invalid parameter address 

1999 Bad refnum 

6001 Attempt to access unopened file 

6002 Attempt to reopen a file which is not closed using an open FIB (file 
info block) 

6005 Operation incompatible with access mode with which file was opened 

6004 Printer offline 

6005 File record type incompatible with character device (must be byte 
sized) 

6006 Bad integer (read) 

6010 Operation incompatible with file type or access mode 

6081 Premature end of exec file 

6082 Invalid exec (temporary) file name 
6085 Attempt to set prefix with null name 

6090 Attempt to move console with exec or output file open 

6101 Bad real (read) 

6151 Attempt to reinitalize heap already in use 

6152 Bad argument to NEW (negative size) 
6155 Insufficient memory for NEW request 
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6154 Attempt to RELEASE outside of heap 
Operating System Error Codes 
The error codes listed delow are generated only when a nonrecoverable error 
occurs while in Operating System code. 

10050 Request block is not chained to a PCB (Undlk_Req) 

10051 Bld_Req is called with interrupts off 

10100 An error was returned from SetUp_Directory or a Data Segment routine 
(SetupJUInfo) 

10102 Error > trying to create shell (Root) 

10103 Sem_Count > 1 (Init_S8m) 

10104 Could not open event channel for shell (Root) 

10197 Automatic stack expansion fault occurred in system code (Check_Stack) 

10198 Need_Mem set for current process while scheduling is disabled 
(SimpieScheduler) 

10199 Attempt to block for reason other than I/O while scheduling is disabled 
(SimpieScheduler) 

10201 Hardware exception occurred while in system code 

10202 No space left from Sigl_Excep call in Hard_Excep 

10203 No space left from Sigl_Excep call in Nmi_Excep 
10205 Error from Wait_Event_Chn called in Excep_PrGlog 

10207 No system data space in Excep_Setup 

10208 No space left from Sigl_Excep call in range error 

10212 Error in Term_Def_Hdl from Enable_Excep 

10213 Error in Force_Term_Excep, no space in Enq_Ex_Data 
10401 Error from Close_Event_Chn in Ec_Cleanup 

10582 Unable to get space in Freeze_Seg 
10590 Fatal memory parity error 

10593 Unable to move memory manager segment during startup 

10594 Unable to swap in a segment during startup 

10595 Unable to get space in Extend_MMlist 

10596 Trying to alter size of segment that is not data or stack (Alt_DS_Size) 

10597 Trying to allocate space to an allocated segment (Alloc_Mem) 

10598 Attempting to allocate a nonfree memory region (Take__Free) 

10600 Error attempting to make timer pipe 

10601 Error from KiIl_Object of an existing timer pipe 

10602 Error from second Make_Pipe to make timer pipe 

10603 Error from Open to open timer pipe 

10604 No syslocal space for head of timer list 

10605 Error during allocate space for timer pipe, or interrupt from 
nonconfigured device 

10609 Interrupt from nonconfigured device 

10610 Error from info about timer pipe 

10611 Spurious interrupt from floppy drive *2 

10612 Spurious interrupt from floppy drive #1, or no syslocal space for timer 
list element 

10613 Error from Read_Data of timer pipe 
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10614 Actual returned from Reacl_Data is not the same as requested from 
timer pipe 

10615 Error from open of the receiver's event channel 

10616 Error from write_Event to the receiver's event channel 

10617 Error from Close_Event_Chn on the receiver's pipe 
10619 No sysglobal space for timer request block 

10624 Attempt to shut down floppy disk controller while drive is still busy 
10637 Not enough memory to initialize system timeout drives 
10675 Spurious timeout on console driver 

10699 Spurious timeout on parallel printer driver 

10700 Mismatch between loader version number and Operating System version 
number 

10701 OS exhausted its internal space during startup 

10702 Cannot make system process 

10703 Cannot kill pseudo-outer process 

10704 Cannot create driver 

10706 Cannot initialize floppy disk driver 

10707 Cannot initialize the File system volume 

10708 Hard disk mount table unreadable 

10709 Cannot map screen data 

10710 Too many slot-based devices 

10724 The boot tracks do not know the right File System version 

10725 Either damaged File System or damaged contents 

10726 Boot device read failed 

10727 The OS will not fit into the available memory 

10728 SYSTEM.OS is missing 

10729 SYSTEM.CONFIG is corrupt 

10730 SYSTEM.OS is corrupt 

10731 SYSTEM.DEBUG or SYSTEM.DEBUG2 is corrupt 

10732 SYSTEM.LLD is corrupt 

10733 Loader ran^ error 

10734 Wrong driver is found. For instance, storing a diskette loader on a 
ProFile 

10735 SYSTEM.LLD is mlSSlng 

10736 SYSTEM.UNPACK is missing 

10737 Unpack of SYSTEM.OS with SYSTEM.UNPACK failed 

11176 Found a pending write request for a pipe while in Close_Object when it 
is called by the last writer of the pipe 

11177 Found a pending read request for a pipe while in Close_Object when it 
is called by the (only possible) reader of the pipe 

11178 Found a pending read request for a pipe while in Read_Data from the 
pipe 

11180 Found a pending write request for a pipe while in Wrlte_Data to the 

pipe 
118XX Error xx from diskette ROM (See OS errors 18xx) 
11901 Call to Getspace or Relspace with a bad parameter, or free pool is bad 
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Workshop Character Set 



B 



D 



BU 



® 



A 



6 



OO 



;-i-: 



SON 



sa 



a 



A 



e 



STX 



DC2 



B 



ETX 



0C5 



/ 



EOT 



DC4 



u 



f 



EW 



NMC 



U 



U 



Vi 



tan 



SVN 



& 



V 



u 



n 



V 



aa 



E1B 



w 



g 



w 



3 



« 



IS 



CM 



( 



8 



H 



d 



(S> 



IT 



» 



NT 



Bl 



) 



& 



6 



IT 



If 



m 



J 



a 



/ 



B 



Vf 



ESC 



K 



[ 



{ 



a 



fF 



FS 



1 



& 



u 



Q 



M 



m 



} 



u 



to 



N 



n 



6 



u 



ti't r t fit uj 



n 



us 



oa 



6 



u 







ITie first 32 characters and DEL are nonprinting control codes. 
The shaded area is reserved for future use. 
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Appendix C 
Screen Control Characters 



To perform standard screen control functions in Pascal^ use the ScreenCtr 
procedure of PASLIBCALL as detailed in Section 5.4. For an alternative 
method of screen control^ you can use WRITE or WRITELN's with the 
corresponding character string from Table C-1. 

In BASIC^ you should use PRINT with the CHR$ function and the argument 
that corresponds to the desired action. For example: 

10 print ctir$(27); chr$(42); chr$(10); chr$(10) 

20 end 

run 

should erase tJne screen^ and position the cursor on the third line. 





Table C-l 
Screen Control Character 


Strings 




Desired function 


single-character string 
ASCII 
Char HEX Decimal 


2-character 
ASCII 
Char HEX 


String 
Decimal 


position to home 


IE 


30 






one position left 


BS 8 


8 






one position right 


FF C 


12 






position up one line 


VT B 


11 






position down one line 


LF A 


10 






erase to end of line 






ESC-T lB-54 


27-84 


erase to end of screen 






ESC-Y lB-59 


27-89 


erase screen 






ESC-** 1B-2A 


27-42 
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Appendix D 
Common Problems 



D.1 What to Do When You Find Yourself in the Debugger D-1 

D.2 How to Stop Your Program D-2 

D.3 What to Do When a Diskette Won't Eject D-2 

D.4 What to Do When You Get a Range Error D-2 

D.5 What to Do When the System Does Not Respond D-2 

D.6 What to Do with a Runaway Exec File D-3 



Common Problems 



This section presents the most common problems that programmers seem to 
have with the Workshop with suggestions for handling them. 

D.1 What to Do When You Find Yourself In the Detjugger 

You can tell you have entered the DetDugger when you suddenly end up with 
cryptic looking numbers and symbols on your screen. You are actually viewing 
the alternate screen, and the numbers and symbols are a disassembly of the 
code where you have stopped aod the values of the machine registen. To 
return to the normal screen to see where you were before you entered the 
Debugger, hold down the [CPTION] key and press the [ENTER] key. Additional 
information on the alternate screen is available in Section 3.2. 

Often the Debugger display will include suggestions for what to do next, such 
as "Press g to continue". Figure D-1 is an example of what appears on the 
screen when you enter the Debugger. 



Leuel 7 Interrupt 
L0CALPR0+88ifi 1D48 FFF5 
PC=0024e022 SR=0000 



PC MOVE.B D0,$FFF5(A6) 

i Ptt=00019 



US=00F7FBEC SS=00CBFEE0 DO 
D0=00100009 Dl=00000008 D2=000000C0 D3=000264A7 
D4=0000000i D5=4EF90084 D6=12CC4EF9 D7=00840000 
A0=00F8126E Fll=00CCA22ft A2=00240060 ft3=00CCft22ft 
A4=00CCA22A A5=00F7FC44 A6=00F7FBFA A7=00F7FBEC 
> 

Figure D-1 
Detxigger Screen Display 

You can enter the Debugger in a number of ways, most commonly by having 
an error in your program, pressing the NMI (nonmaskable interrupt) key, or 
having a memory parity error. The NMI key Is the "-" key on the numeric 
keypad. 

More information on handling the Debugger is given in Chapter 8. Section 8.2 
will help you handle accidental entry Into the Debugger. Section 6.5.2 
contains Information aboout Pascal rm-time enors, particularly range errors. 
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U3. How to Stop Your Program 

If your program has been running for longer than you think it needs to^ it 
might be in an infinite loop. Before you stop the program^ you should: 

• Check the alternate screen. Maybe your program is waiting for input. 

• Try il-period to see If it responds. 

If neither of these actions works, press the Nfl^I key, which stops your program 
in the Debugger. See Section 8.2 for information about what you can do from 
the Debugger. 

D.3 What to Do When a Diskette Wont Eject 

The eject request buttons are only recognized after the Workshop system does 
a Pascal I/O operation. Thus when you press an eject button, nothing will 
happen until you press a key, or I/O happens for some other reason. (When 
you are in the Editor, the Preferences tool, or TransferProgram, you do not 
need to hit a key after pressing the diskette buttoa) 

In general, if a diskette will not eject, it means that the file system still has 
some file open on it Use the Online command to check the open count, 
which will tell you if any files are still opea Then use the List command 
from the File Manager to list the contents of the diskette. If some files are 
open, there is probably a resident process that has a file open or a data 
segment open that has been mapped to the disk. Use the ManageProcess 
subsystem in the System Manager to kill the process. This will close the files 
and the disk will eject. 

Further information on the List command can be found in Sections 2.3 and 2.6. 
The ManageProcess subsystem is described in Section 3.4. 

D.4 What to Do When You Get a Range Error 

A range error drops you into the Debugger. Instructions for handling range 
errors are in Section 8.3.2. 

D5 What to Do When the System Does Not Respond 

Some of the reasons your Workshop might not respond are: 

1. You might be running a program with an infinite loop. 

2. You might have stopped console output by pressing #-S. 

3. You might have the alternate screen showing. 

4. You might have altered the NMI character. 

Press the NMl key (the "-"key on the numeric keypad) to drop into the 
Debugger. See Section 8.2 for further instructions. 

If pressing the NMI key does not work, power off your Lisa and reboot the 
system. 
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D.6 What to Do with a Runaway Exec File 

If you think that your exec file has gone wUd^ how do you stop it? 

When the exec file processor has finished processing your exec file (s), it has 
created a temporary file with the stream of characters that are to perform 
the actions In the exec file. The Workshop then sets the am-tlme 
environment so that standard input comes from the temporary flle^ axJ begins 
executing the commands In the temporary file. While they are executing, the 
Workshop Ignores the keytraard, although the characten you type will be 
remembered. 

You can terminate standard Workshop programs by pressing «-period, although 
termination might not be Immediate If the program being run does not 
recogilze «-perlod. 

NOTE 

Note that most Workshop tools check for 4-perlod from the keyboard 
even when running under exec files. This means that you cstfi abort 
Workshop tools In exec files. 

Unless user programs are written to recognize the «-perlod key combination 
as ai abort mechanism, pressing those keys will not terminate the exec file If 
a user program Is being run. (See PASLIBCALU Section 5.4, for information 
on the function PAbortFlag, which tells whether or not those keys have been 
pressed.) If this is the case, you can either: 

• wait for the user program to terminate so that #-period can be 
recognized by something else, or 

• press the NMI key, which forces the system Into the Debugger. 

If the user program does recognize ^-period, pressing it will terminate the 
program but not the exec file. To terminate the exec file, wait until the 
Workshop prompt appears and press ^-period again. 

See Section 8.2 for instructions on how to stop a user program early. 
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Index 



active document A. 2 

AddResident command 3.4 

address error exception 8.2.1.1 

addressing modes 6.4.5 

All Occurrences 4.7 

alternate screen 1.1 

•-period key 1.5.2, 5.4.1 

«-s key 1.5.3 

ASCII Assembler directive 6.5.1 

Assemble command 1.3 

Assemble instruction in Debugger 
8.4.5 

Assembler 6 

addressing modes 6.4.5 
assemble from exec file 9.4.1 
Assembler directives 6.5 
calling Pascal I/O 6.7.4 
comments in program 6.4.7 
conditional assembly directives 

6.5.3 
constants 6.4.2 
current program location 6.4.7 
error messages A.l 
expressions 6.4.5 
external reference directives 

6.5.4 
function, how to write 6.7.3 
generic instructions 6.3 
labels and local labels 6.4.4 
listing file 6.2.4 
macro directives 6.5.1 
object file 6.2.3 
opcodes 6.3 
operators 6.4.5 
options 6.2.1 
Pascal data areas 6.7.5 
program structure 6.4.1 
pseudo-ops 6.5 
space allocation directives 
6.5.1 

asterisk 6.4.7 



B 

Backup command 2.3.1, 2.7 
BASIC 

installing 1.10 

Interpreter l.ll 
Basic command 1.3 
Baud Rate menu 10.3 
.BLOCK Assembler directive 6.5.1 
block-structured device 2.4.1 
Boolean expression, in exec file 

9.2.4.1 
Boolean function, in exec file 

9.2.4.2 
boot device 3.3.2 
booting 1.2 
breakpoint. Debugger 8.2.1.3, 

8.4.6 
bus error 8.2.1.1 
.BYTE Assembler directive 6.5.1 
ByteDiff utility 11.2 



Cases Must Agree 4.7 
Cases Need Not Agree 4.7 
chaining exec files 9.4.5 
ChangeSeg utility 11.2 
changing a volume or file name 

2.10 
character set, Lisa B 
aEAR key 1.5.1.1 
Clipboard 4.1, 4.6 
Cobol command 1.3 
CodeSlze utility 11.3 
command file. Linker 7.2 
command line 

File Manager 2.2, 2.3 

System Manager 3.2 

Workshop 1.1, 1.3 
commands. Debugger 8.5 
comments in Assembler program 

6.4.7 

comments in exec file 9.3.1 
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communications. See Transfer 

program, 
comparing binary files 11. 1 
comparing .TEXT files 11.4 
Compiler, Pascal 5 
Comjjiler commands, Pascal 5.3 
CONCAT function in exec file 

9.2.4.4 
conditional assembly directives 

6.5.3 
configuring an RS232 port 11.10 
connectors 3.3.3 
Console command 5.2 
constants. Assembler 6.4.2 
Control menu 10.3 
Convenience Settings 3.3.1 
Copy 4.6 

Copy command 2.3.2, 2.7 
copying 

files 2.7 

text 4.2.4 
cross-reference, Pascal 11.12, 

11.13 
cross-reference utility 
current program location. 

Assembler 6,4.7 
Cut 4.6 
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11.9 



data communications. See Transfer 
program. 

date, file 9.2.4.2 

dead code analysis 7.1.1, 7.8 

Debug command 1.3 

Debugger 8 

Assemble instruction 8.4.5 
breakpoint 8.2.1.3, 8.4.6 
commands 8.3-8.5 
Disassemble instruction 8.4.5 
display memory 8.4.2 
display registers 8.4.4 
execution time, measuring 8.4.8 
memory dump to diskette 8.4.9.5 
memory management hardware, 

changing 8.4.7 
NHI key, setting 8.4.9.3 



6.5.4 
,2.2. 



.3.3 



printing 8.4.9.4 
problem diagnosis D.l 
and run time stack 6.6.1 
search memory 8.4.3 
symbols and base conversion 

8.4.9.1 

trace commands 8.4.6 

UBR command 8.2.1.3 

window, moving 8.4.9.2 
.DEF Assembler directive 
DEFAULT exec file command 9. 
DefaultPrinter command 3.2 
Delete command 2.3.3, 2.8 
DeleteResident command 3.4 
deleting a file 2.8 
Device Connections option 3. 
DEVICE_CONTROL system call 5.4.1 
Differentiated Keywords 4.9 
Diff utility 11.4 
directives. Assembler 6.5 
directory, working 1,4 
Disassemble instruction. Debugger 

8.4.5 
disassembler utility 11.5 
diskette 

mounting and unmounting 
1.5.4 

nonejecting D.3 

volume 2.4.1 
domain 8.2.1.2 
dumping a file 11.6 
DumpObj utility 11.5 
DumpPatch utility 11.6 
Duplex menu 10.3 
Duplicate... 4.5 



Edit 




Cut 4.6 




Paste 4.6 




Edit coiiiiiand 


1.3 


Edit menu 4.2.2, 4.6 


Editor 4 




copying text 4.2.4 


Edit menu 


4.2.2, 4.6 


File menu 


4.2.2, 4.5 
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menus 4.2.2 

multiple files 4.2.4 

operations 4,2.1 

Print menu 4.9 

Search menu 4.2.2, 4.7 

Type Style menu 4.2.2, 4.8 
.ELSE Assembler directive 6.5.3 
ELSE exec file command 9,2.4 
ELSEIF exec file command 9.2.4 
.ENDC Assembler directive 6.5.3 
ENOIF exec file command 9.2.4 
.ENDM Assembler directive 6.5,2 
Environments window. 1.2 
Equal command 2.3.9 
error messages A 

Assembler A.l 

Linker A. 2 

ObjIOLib A. 3 

Operating System A. 4 
errors, program. See program bugs, 
errors in exec file 9.6 
escape key 1.5.1.1 
exception handler 8.2.1.1 
exec file 9 

as function 9.4.8 

assembly 9.4.1 

Boolean expression 9.2.4.1 

Boolean function 9.2.4.2 

chaining 9.4.5 

command lines 9.2 

comments 9.2, 9.3.1 

CONCAT string function 9.2.4.4 

conditional statements 9.2.4 

DEFAULT command 9.2.2.1 

ELSE command 9.2.4 

ELSEIF command 9.2.4 

ENDIF command 9.2.4 

errors 9.6 

EXISTS function 9.2.4.2 

function calls 9.2.5.3 

IF command 9.2.4 

nesting 9.2.5 

hEWER function 9.2.4.2 

options 9.3 

parameter list 9.3 

parameters 9.2 



Pascal compile 9.4.1, 9.4.3, 

9.4.4, 9.4.6 

processor 9.3 
programming tips 9.5 
READCH command 9.2.3.1 
READLN command 9.2.3.1 
recursive function 9.4.6 
REQUEST command 9.2.2.2 
. RETURN command 9.2.5.2 
SET command 9.2.2.1 
statements 9.2 
stopping execution D.6 
string expressions 9.2.4.3 
string functions 9.2.4.4 
SUBMIT command 9.2.5.1, 9.3.1.1 
temporary file 9.1, 9.3.1.1 
UPPERCASE string function 

9.2.4.4 
WRITE command 9.2.3.2 
WRITELN command 9.2.3.2 
execution time, measuring 8.4.8 
EXISTS exec file function 9.2.4.2 
Exit Editor 4.5 
expressions. Assembler 6.4.5 
extension to file name 2.4.3 
external procedures and functions, 

6.6 
external reference directives. 

Assembler 6.5.4 
external references, resolving 
7.1, 7.7 



file 

copying 2.7 

deleting 2.8 

dump utility 11.6 

exec temporary 9.1 

FileDiv utility 11.7 

listing 2.6 

patch utility 11.6 

search utility 11.8 
FileAttributes command 2.3.10 
file date 9.2.4.2 
FileDiv utility 11.7 
FileJoin utility 11.7 
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,10 



10 
2.4.1 



File Manager 2 
File Manager commands 

Backup 2.3.1^ 2.7 

Clear Attributes 2.3 

Copy^ 2.3.2 2.7 

Delete, 2.3.3 2.8 

Equal 2.3.9 

FileAttributes 2.3 

Initialize, 2.3.11, 

List 2.3.4, 2.6 

Mount 2.3.12 

Names 2.3.13, 2.6 

Online 2.3.14 

Prefix 2.3.5 

Protect 2.3.10 

Quit 2.3.8 

Rename 2.10, 2.3.6 

Safety 2.3.10 

Scavenge 2.3.15 

Transfer 2.3.7 

Unmount 2.3.16 
File menu 4.2.2 
FILE-M6R command 1.3 
file name 1.4, 4.5 

changing 2.10 

prompts 1.5.1, 1.5.1.2-1.5. 

standard extension 2.4.3 
file specifier 2.2, 2.4.2, 2.5 
FilesPrivate command 3.2 
Find... 4.7 
Find & Paste All 4.7 
Find Same 4.7 
Find utility 11.8 
font 4.8 

full duplex. See Duplex menu. 
Full Footers 4.9 
function, how to write in 

Assembler 6.7.3 
function as exec file 9.4.8 
function calls in exec file 

9.2.5.3 
function result 6.6.1 



2.9 



1.6 



generic instructions. Assembler 

6.3 

GetGPrefix procedure, Pascal 5.4.1 
GetPrDevice procedure, Pascal 

5.4.1 
global cross-reference utility 

11.9 
global name 7.7 
GXRef utility 11.9 
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half duplex. See Duplex menu. 
Handshake menu 10.3 
hardware exception 8.2.1.1 
HEAD macro 6.6.1 
heap, Pascal 5.4.2 
HEAPRESULT, Pascal heap routine 

5.4.2 
help 1.5.1.7 



1 

I-code 5.1, 5.2, 5.2,1 

.IF Assembler directive 6.5.3 

IF exec file command 9.2.4 

.1 file extension 2.4.3 

.INaUDE Assembler directive 6.5.5 

infinite loop 8.2.1.2, D.2 

Initialize command 2.3.11, 2.4.1, 

2.9 
insertion point 4.1, 4.3.1 
installing 

BASIC 1.10 

COBOL 1.12 

Pascal 1.7 
intrinsic units 7.5 



keyboard repeat delay 3.3.1 
KillProcess commands 3.4 



Generate command 1.3 



labels. Assembler 6.4.4 
.LIB file extension 2.4. 
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Link conmand 1.3 
Linker 7 

error messages A. 2 

listing 7.6 

options 7.3 
Lisa character set B 
•LIST Assembler directive 6.5.5 
List command 2.3.4^ 2.6 
listing file^ Assembler 6.2.4 
listing files 2.6 
Literal search 4.7 
local labels. Assembler 6.4.4 
local name 7.7 

.LONG Assembler directive 6.5.1 
loop 8.2.1.2, D.2 



-M- 



-N- 



. MACRO Assembler directive 6.5.1 
macro directives. Assembler 6.5.1 
.MACROLIST Assembler directive 

6.5.5 

main command line. See Workshop 

ccMnn»ids line, 
main program, linking 7.4 
main screen 1.1 
MakeBackground command 1.3 
ManageProcess command 3.2 
HARK, Pascal heap routine 5.4.2 
MEMAVAIL, Pascal heap routine 

5.4.2 
memory 

display in Debugger 8.4.2 

dumping to diskette 
8.4.9.5 

parameter memory 3.3, 3.3.5 

test 3.3.2 
memory management hardware, 

changing 8,4.7 
modem 10.2, 10.3 
Mount command 2.3.12 
mounting a diskette 1.5.4 
mouse 4.1 

mouse double click delay 3.3.1 
moving the display window 4.4.2 



Names command 2.3.13, 2.6 

nesting exec files 9.2.5 

NEW, Pascal heap routine 5.4.2 

NEWER exec file function 9.2.4.2 

NMI key 8.3, 8.4.9.3 

.NOLIST Assentoler directive 6.5.5 

.NOMACROLIST Assembler directive 

6.5.5 
nonmaskable interrupt key (NMI) 8.3, 

8.4.9.3 
.NOPATCHLIST Assembler directive 

6.5.5 



.OBJ file extension 2.4.3 

object code, Pascal 5.1, 5.2.1, 7.1 

Object file. Assembler 6.2.3, 7.1 

ObjIOLib errors A. 3 

Online command 2.3.14 

opcodes. Assembler 6.3 

Open... 4.5 

Operating System error messages 

A.4 
operators. Assembler 6.4.5 
options for file name prompts 

1.5.1.7 
options in exec file 9.3 
.ORG Assembler directive 6.5.1 
OutputRedirect command 3.2 



PAbortFlag function, Pascal 5.4.1 
.PAGE Assembler directive 6.5.5 
Page Number Only 4.9 
parameter list in exec file 9.3 
parameter memory 3.3, 3.3.5 
parameter passing 6.6.3 
Parity menu 10.3 
Pascal Compiler 5 
Pascal 

compile from exec file 9.4.1, 
9.4.3, 9.4.4, 9.4.6 

Compiler commands 5.3 
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cross-reference utility 11.12. 

11.13 
heap 5.4.2 
HEAPRESULT 5.4.2 
MARK 5.4.2 
HEMAVAIL 5.4.2 
NEW 5.4.2 

Object code 5.1, 5.2.1 
printing a program 4.9 
RELEASE 5.4.2 

Pascal cofimand 1.3 
PASLIBCALL unit, Pascal 5.4.1 
Paste 4.6 

patching a file 11.6 
.PATCHLIST Assembler directive 
6.5.5 

pathnarne 1.5.1 
Plain keywords 4.9 
PLINITHEAP procedure, Pascal 

5.4.1, 5.4.2 
PortConfig utility 11. 10 
Preferences command 3.2, 3.3 

Convenience settings 3.3.1 

Device Connections 3.3.3 

Rates 3.3.1 

Screen Contrast 3.3.1 

Speaker Volume 3.3.1 

Startup option 3.3.2 

Tools menu 3.3.5 

Workshop option 3.3.4 
prefix 2.4.3 
Prefix command 2.3.5 
pretty listing. Assembler option 

6.2.1, 6.2.4 
Print All of Document 4.9 
printer 1.14 
printing 

from the Debugger 8.4.9.4 

Pascal programs 4.9 
Print menu 4.2.2, 4.9 
Print Selection 4.9 
problems D 

procedure arguments 6.6.1 
Process Management commands 

AddResident 3.4 

OeleteResident 3 . 4 

Kil Process 3.4 



ProcessStatus 3.4 

Quit 3.4 
processor, exec file 9.3 
ProcessStatus command 3.4 
program bugs 8.2.1 
programming tips, for exec file 

9.5 
program structure. Assembler 6.4.1 
protected master 2.3.10 
pseudo-ops 6.5 



Quit command 1.3, 2.3.8, 3.2, 3.4 
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range check error 8.2.1.1, 8.3.2 

Rates option 3.3.1 

READCH exec file command 9.2.3.1 

READLN exec file command 9.2.3.1 

recursive function 9.4.6 

.REF Assembler directive 6.5.4 

register conventions 6.6.2, 8.4.1 

registers, display in Debugger 

8.4.4 
regular units 7.5 
RELEASE, Pascal heap routine 5.4.2 
remote computer 10.1, 10.2 
Rename command 2.10, 2.3.6 
REQUEST exec file command 9.2.2.2 
RETURN exec file command 9.2.5.2 
Revert to Previous Version 4.5 
.RORG Assembler directive 6.5.1 
RS232 port, configuring 11. 10 
Run command 1.3 
running 

Assembly language program 1.8 

Pascal program 1.8 
run time stack 6.6.1 



Save a Copy in... 4.5 
Save & Continue 4.5 
Save a Put Away 4.5 
Scavenge command 2.3.15 
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Screen Contrast option 3.3.1 
screen control 

characters C 

functions 5.4.1 

stopping the display 1.5.3 
ScreenCtr procedure^ Pascal 5.4.1 
scrolling 4.4.1 
search file for pattern 11.8 
Search menu 4.2.2, 4.7 
.SE6 Assembler directive 6.5.4 
SegMap utility il.ii 
segmentation 11.3, 7.9 
segment map utility li.ll 
segment name 

Assembler 6.5.4 

changing 11.2 
Select All of Document 4.6 
selecting text 4.3 
Separate Identifiers 4.7 
SET exec file command 9.2.2.1 
Set Tabs 4.6 

setting Workshop parameters 3.3.4 
Shift Left 4.6 
Shift Right 4.6 
space allocation directives. 

Assembler 6.5.1 
Speaker Volume option 3.3.1 
stack 6.6.1 
stack overflow 8.2.1.1 
Startup option 3.3.2 
statement, in exec file 9.2 
static link 6.6.1 
stationery 4.2.3 
stopping 

screen display 1,5.3 

operation 1.5.2 
string expressions, in exec file 

9.2.4.3 
SUBhIT exec file command 9.2.5.1, 

9.3.1.1 
SXRef utility 11.12 
symbolic references 7.1 
system malfunctions 8,2.2 
System Manager 3 
System Manager commands 

Console 3.2 

Convenience Settings 3.3.1 



DefaultPrlnter 3.2 
FilesPrivate 3.2 
ManageProcess 3.2 
outputRedirect 3.2 
Preferences 3.2, 3.: 
Quit 3.2 
Time 3.2 
Validate 3.2 
SYSTEM-MGR command 1.3 



TAIL macro 6.6.1 

TAS Assembler opcode 6.3 

Tear Off stationery 4.5 

temporary exec file 9.3.1.1 

test and set instruction 6.3 

text, selecting 4.3 

.TEXT file extension 2.4.3 

Time command 3.2 

.TITLE Assembler directive 6.5.5 

Token search 4.7 

Tools menu 3.3.5 

trace commands in Debugger 8.4.6 

Transfer command 2.3.7 

Transfer program 10 

TransferProgram command 1.3 

Type style menu 4.2.2, 4.8 



-U- 



UBR command. Debugger 8.2.1.3 
underlining 4.9 
Undo Last Change 4.6 
Unmount command 2.3.16 
unmounting a diskette 1.5.4 
UPPERCASE function, in exec file 

9.2.4.4 
user break facility 8.2.1.3 
utilities 11 

ByteDiff 11.1 

ChangeSeg 11.2 

CodeSize 11.3 

comparing binary files 

comparing .TEXT files 

Diff 11.4 

disassembler 11.5 



11.1 

11.4 
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dump a file 11.6 

DunpObj 11.5 

DumpPatch 11.6 

FileDiv 11.7 

FileJoln 11.7 

Find 11.8 

GXRef 11.9 

patch a file 11.6 

PortConfig 11.10 

search file for pattern 11.8 

segriap ii.ii 

segmentation 11 .3 

segment mapping 11.3 

SXRef 11.12 

UXRef 11.13 
UXRef utility 11.13 



SYSTEM-MGR 1.3 

TransferProgram 1.3 
Workshop option 3.3.4 
WRITE exec file conmand 9.2.3.2 
WRITELN exec file command 9.2.3.2 
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Validate command 

volume 2.4.1 

changing the name 
creating 2.9 



2.10 



wild card characters 2.5 
itfindow 

Debugger 8.4.9.2 

Envirarwents 1.2 
window, moving 4.4.2 
.WORD Assembler directive 
working directory 1.4, 2. 
Workshop command line 1. 
Workshop commands 

Assemble 1.3 

Basic 1.3 

Cobol 1.3 

Debug 1.3 

Edit 1,3 

FILE-MGR 1.3 
Generate 1.3 
Link 1.3 

Makebackground 1 . 3 
Pascal 1.3 
Quit 1,3 
Run 1.3 



6.5.1 
4.3 
1, 1.3 
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Workshop User's Guide MaJJ-Back Form 

Apple publications would like to leam about readers and what you think atxxit this 
manual in order to make better manuals in the future. Please fill out this form^ or 
write all over it and send it to us. We promise to read it 

How are you using this manual? 

[ ] learning to use the product [ ] reference [ ] both reference and learning 

[ ] other 

Is it quick and easy to find the information you need in this manual? 
[ ] always [ ] often [ ] sometimes [ ] seldom [ ] never 

Comments 

What makes this manual easy to use? 



What makes this manual hard to use? 



What do you like most about the manual?. 



What do you like least about the manual?. 



Please comment on^ for example, accuracy, level of detail, number and usefulness of 
examples, length or brevity of explanation, style, use of graphics, usefulness of the 
index, organization, suitability to your particular needs, readability. 



What languages do you use on your Lisa? (check each) 

[] Pascal [] BASIC [] COBOL [] other 

htow lof^ have you been programming? 



[ ] 0-1 years [ ] 1-3 [ ] 4-7 [ ] over 7 I ] not a programmer 

What is your Job tiUe?__^ 

Have you completed: 

[ ] high school [ ] some college [ ] BA/BS [ ] MA/MS [ ] more 

What magazines do you read? 



other comments (please attach more sheets if necessary). 
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Pascal for the Lisa 

Release 2.0 Notes 



What's in Uie Pascal Release Notes? 

These notes describe sitLiatlons that were brought to our attention after It 
was too late to document them in the Pascal manuals. 

Insert the notes in the back of the manual^ so that you can refer to them as 
necessary. Included in these notes are revised versions of the Mjikshop 
User^ Gufde f^pperfAx B and the Pascal Refiaience Manual fippenilx I to 
replace the copies bound in your manuals; take a moment now to make the 
substitutions. 

If you have a question or a problem that you can't resolve using the manuals 
or these notes^ call the Lisa Telephone Stfjport Line^ (800) 553-4000. 
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Workshop To install the Pascal language and Workshop software from 
Chapter 1 the set of micro diskettes F»ckaged in your language manual 
binder^ refer to Installing the Office System Software in 
Appendix G^ Set Up Procedures^ in the Lisa Owners Gufds If 
you plan to use the Office Systenrt, you must first install the 
Office System 2.0 micro diskettes. You do not need to install 
the Office System software if you intend to do only language 
development work. Before you insert the micro diskettes, make 
sure you can see the red tabs from the front of the micro 
diskettes. Start installing with steps 1, 2, and 3 on page G31. 
Then follow this sequence: 

4> Turn the Lisa on by pressing the on-off button once. After 
a few seconds, youll hear a click; immediately press the 
spacebar. 

5> The Lisa goes through a self-test When a menu of symbols 
appears in the upper left-hand comer of the screen, press 
and hold down the Apple key while you type a 2 ~ on the 
main keyboard, not on the numeric keypad. 

6> When the main menu shown on page G32 appears, click the 
mouse once on the Install box 

7> When the alert box with the message "TTie Lisa is installing 
startup software version 2.0" appears, click Don't Erase. 
When the first micro diskette is installed, it will eject 
Continue installation by following the Owners Guide 
instructions from step 6, inserting the remaining language 
diskettes In order. 

Workshop After successfully adding Pascal to a ProFlle containing the 
Chapter 1 Office Systenv If the system Is merely allowed to reboot, the 
default of the Environments window will cause the Workshop 
shell to start up. To cause the Initialization to pause at the 
Environments window In order to examine or change the default^ 
press the space bar after the machine self- test, while the 
hourglass Icon Is showing. 

Workshop If you have just printed anything on a daisy wheel printer from 
Chapter 1 the Office Systerrv and you return to the Workshop using the 
Environments window, printing to logical device "-printer" will 
be garbled until the printer Is switched off and then on agala 
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Workshop The print commands of the Editor always use the logical device 
Chapter 1 "-printer set in the System Manager. Choosing Daisy Wheel 
Printer or Dot Matrix Printer from the Print menu does not 
change the system's configuratiort but only adjusts the Editor to 
the intended device. 

Workshop Any program intended to run as a l)ackground process 
Chapter 1 (MakeBackgroundProcess) must include frequent and judicious 
calls to the Operating System procedure Yield_CPU. Hence^ 
system utilities should never be run in the background. Also^ a 
background process should not have any interaction with the 
console^ and it cannot pull events from the hardware event 
queue. 

Workshop Designate user files with the pathname "SHELL." only if you 
Chapter 2 want them to appear in the Environments window as an 
alternative shell. 

Workshop You cannot directly rename a file to a name that differs from 
Chapter 2 the original only in the case of the characters^ because the 
internal representation of the names is the same. Instead^ 
rename the file to a temporary name^ and then change that 
to the name you want 

Workshop If you unmount the prefix volume by ejecting the diskette^ 
Chapter 2 Scavenging the volume^ or using the Unmount commanct 
the boot volume automatically becomes the prefix volume. 

Workshop Assume that a file FOO.TEXT has been damaged and no longer 
Chapter 2 has the internal representation of a textfile. If the user enters 
the File Manager and tries to COPY the file to -PRINTEFC the 
system generates a bus error and enters the Debugger. 

Workshop The Output Redirect function of the System Manager does not 
Chapter 3 correctly handle screen output that uses QOTOXY^ for example^ 
screen output done by the File Manager when listing wildcard 
matches. This results in redirected output to the printer being 
overwritten on one lina 

Workshop Use "-printer" instead of "-RS232-B" when redirecting output to 
Chapter 3 the printer. 
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Workshop If you change the name of a suspended file ~ such as the 
Chapter 3 Pascal compiler — and attempt to manage the process from the 
System Manager^ the new name appears in the pathname^ but 
you must still use the rzA/name to kill the process. 

Workshop TTie Editor changes the creation date of a text file to the 
Chapter 4 current date each time the file is modified. 

Workshop If the initialization of the Ecfltor fails due to lack of disk space 
Chapter 4 (error 309i and space on the disk is then made free^ the next 
attempt to start the Editor will also fail (error 304X You must 
enter the Process Manager of the System Manager^ KILL the 
Editor process^ and then retry. 

Workshop The language processors^ Editor, and other utilities of the 
Chapter 4 WorkshoiD expect as input a standard .TEXT fila The internal 
structure of a text file in a block-structured device is 
described in the Lisa Pascal Reference Manual: 

• Each page (two 512-byte blocks) contains some number of 
complete lines of text and is padded with null characters 
(ASCn 0) after the last line as necessary to complete the 
page. 

• Two 512-byte header blocks are also present at the 
beginning of the file. These may or may not contain 
informatioa 

• A sequence of spaces (ASCII 32 decimal, $20 hexadecimal) 
can be compressed into a 2-byte code namely^ a OLE 
character (ASCII 16 decimal, $10 hexadecimal), followed by a 
byte containing the value 32 decirBal plus the number of 
spaces represented. 

Workshop The file name TAPERTEXT* is reserved for the default 
Chapter 4 stationery template of the Editor and should not be used for 
other purposes. 
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Workshop Attempting to enter or paste more than about 1000 characters 
Chapter a Into one line causes a bus error. If you have a Debugger^ type 
<g> to recover and exit the Workshop shell before running the 
Editor agalrv otherwise no menus appear and you must use NMI 
andOSQUIT. 

Workshop A triple-click will not select the last line in a file unless that 
Chapter 4 line ends with a carriage retura 

Workshop If you are working on many files ~ or a few large files ~ and 
Chapter 4 the Editor becomes sluggish, save and put away the files. Then 
either exit the Workshop shell and run the Workshop shell agairv 
or use the DeleteResident command of the Manage Process 
subsystem of the System Manager to temporarily delete the 
Editor from the list of resident processes. 

Workshop When using the Tear Off Stationery command, type in the 
Chapter 4 volume name if it differs from your boot volume. 

Workshop Cursor residue might be left on the screen in the Editor and the 
Chapters 4 Transfer program, especially after an error message has 
and 10 appeared. 

Workshop The names of files created by the Editor and Transfer will be 
Chapters 4 changed to be all upper case, regardless of how they are typed 
and 10 ia 

Workshop If multiple errors occur during a link^ due an to attempt to link 
Chapter 7 regular units with intrinsic units, the Linker will terminate after 
reporting only the first error. 

Workshop When the Linker detects the error of duplicate entry names — 
Chapter 7 for example after it reads the same file twice — the error 

message may be difficult to interpret because it is formatted 

incorrectly. 

Workshop If an intrinsic unit is linked but not needed (Le. no units in its 
Chapter 7 library file are usedl the Linker generates error 24: unexpected 
block type in lU file. 
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Workshop 
Chapter 10 



Workshop 
Chapter 10 

Workshop 
Chapter 10 



Workshop 
Chapter 10 



For the Debugger^ >PR 2 is print to SLOT2CHAN2, not 
SL0T2CHAN1. LiJDper and lower are reversed In the manual. 

The exec file preprocessor does not have an easy way to input 
single spaces, even though these are required to respond to 
some Workshop messages: While waiting for a space inputs the 
rest of the exec file is consumed without effect Either set up 
your exec files so they don't require space inputs^ or eliminate 
all spaces except the one you want and use the no-space option 
in the preprocessor. 

In an exec flle^ an attempt to pass a literal **%" to a program 
such as CODESIZE will not work. 

Display of error message 647 while you are using the Transfer 
utility probably indicates that after a timeout the program has 
failed to receive the appropriate handshake from the host 

If you type any key during "Playt)ack from what file" in the 
Transfer progranrv the playback will abort 

If you use the Transfer program to make contact with a host 
computer, and you exit the program without logging off 
explicitly, the connection will not be automatically terminated. 
This is usually a convenience, but might not meet user 
expectations. 

When the Workshop shell is initialized, all serial ports are 
configured by default as if they were printers (e.g., 9600 baud, 
DTR handshake, automatic linefeed insertion^ whether or not 
they are listed as such by Preferences. If you subsequently use 
and then exit the Transfer prograrrv the printer configuration is 
restored automatically for ONLY those ports listed In 
Preferences as printers; others will retain the properties set by 
the Transfer program. The Editor will not reconfigure ports that 
have been changed by PortConfig. 
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Workshop To terminate recording to a file opened by the Transfer program 
Chapter 10 during "Record to", open the Control menu and again select 
"Record to". This terminates recording and closes the file. 
Note that, unlike the Editor, Transfer does not automatically 
insert a carriage return at the end of the file. If you use this 
recording to capture text such as a source progranx and the 
language processor (such as BASIC-Plus) expects to see a 
carriage return at the end of the file, attempting to run the raw 
recorded text might cause the system to hang. 

Workshop The manual states that the default handshake in the Transfer 
Chapter ID program Is XOn/XOff. The correct default is None. 

Workshop Because most progran^ do not allow you to eject a disk in 
Ch8f)ter 11 while they are running, plan ahead In large transactions, such 
as mass transfers, to allow a pause for changing disks. 

Workshop The GXRef utility accepts a maximum of 4095 procedure names. 
Chapter 11 

Workshop You cannot exit the ChangeSeg utility by typing <CR> In 
Chapter 11 response to the first prompt line, T=^ile to Change'. You must 
type <CLEAR><CR>. 

Workshop ASCII characters in the range hex 20 through hex 7E are 
Appendix B supported for screen display, for printing on a dot matrix 

printer, and for printing on a daisy wheel printer with the 

fdllowing print wheels: 

• Gothic, 15 pitch 

• Prestige Elite, 12 pitch 

• Courier, 10 pitch 

• Boldface/Executive^ PS. 

Printing ASCII characters to a daisy wheel printer is not 
supported fdr the three print wheels with Modem type styles. 

The character set In the Appendix should show the full Usa 
character set All of the additional characters can be displayed 
on the screea Selected subsets can be printed on dot matrix 
and daisy wheel printers. A new page B-1 Is attached; take a 
moment now to make the substltutioa 
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Workshop If you wish to to position the cursor at coordinates (>cy) 
Appendix C on the screen^ use the two-character sequence <ESC>- (HEX 

1B-3D^ decimal 27-61) followed by the screen's y coordinate and 
then the screen's x coordinate ~ note the order of the supplied 
arguments. The range for the screen's y-axis is from ASCII 
decimal 32 (<SPACE> on the keyboard)^ representing a screen 
coordinate of 0^ through ASCII decimal 63 (? on the keyboard)^ 
representing a screen coordinate of 31. The range for the 
screen's x-axis is from ASCII decimal 32 (<SPACE> on the 
keyboard), representing a screen coordinate of 0^ through ASCII 
decimal 119 (w on the keyboard)^ representing a screen 
coordinate of 87. If you supply coordinates outside these 
ranges^ a bus error may result. Refer to the revised Appendix 
B, supplied with these release notes, for a complete chart of 
character equivalents. 

For example, in BASIC, either of the two statements below 
would place the cursor at position x-0^ y-1. 

PRINT CHR$(27); "-"; "f; " "; 
or 

PRINT CHR$(27); CHR$(61); CHR$(33); CHR$(32); 
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Pascal Avoid labeling an ELSE clause. The following code results in a 

crater 2 bus error when it executes: 

GOTO 1; /iesults in bus error. 

IF TRUE THEN 
ELSE 
1: iRITECGOOO*); 

IF TRUE THEN Carpi Jes correctly. 

ELSE 

•RITECGOOO'); 

Pascal Continuing compilation after notification of the use of incorrect 

Chapter 3 syntax in a SET type declaration 0-e. parentheses used instead 
of square brackets) is fatal 

Pascal The result of a (fivision (of integers) by zero is -1. 

Ch^ter 3 

Pascal If a variable T is defined as T5>ACKED AF^F^YlO^lOO] OF 

Chapter 5 0-255^ the statement Til] :- 255 Is not accepted by the compiler. 
Use TEMP :- 255; Til) :- TEMP; as a workaround. The same is 
true for all subranges from 0,128 to 0..255 and for all constant 
values from 128 to 255. 

Pascal An assignment includinq the same function call as an array 

Chapter 7 index on the left and right will cause fatal errors during 

compilatioa Insteait assign the index to a temporary variable 
before manipulating the array. Compare these examples: 

A[ORD(X)]:«A[ORD(X)) + Ij Causes compilation errors. 

TEMP : «ORD(X); Oh^- does not cause errors. 

A[TEMP]:-A[TEMP) ♦ 1 
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Pascal If a USES statement including the $U compiler option is 

Ctrapter 9 followed on the same line by a comment (or another unit name), 

the trailing comma must be separated followed by a blank; 

otherwise^ the code will be incorrectly parsed. Compare the 

examples: 

USES ($U foaobj unitl^commentj IncorrecL 

{$U bar.obB unit2; 

USES ($U foo.obfl unitl, {comment OhC 

{$U bar.ob3 unit^; 

Pascal The example unit on page 9-3 contains a typographical error 

Chapter 9 that leads to a bus error. For proper syntax in Lisa Pascal^ 
a semicolon ought to appear after the second-to-last end 

Addl:=Incr*l 
end; 
end. 

Pascal Values cannot be read directly Into a real array. Use a 

Chapter 10 temporary variable for reading, and then assign to an array 
element 

Pascal An Input of "-" to a real array is fataL Use an intermediate 

Chapter 10 variable to read values and check for validity^ and then assign 
array elements. 

Pascal When a program uses REWRITE to create a file named 

Chapter 10 "foatext/ the catalog shows the filename as TOO.TEXT"; the 
filename will be changed to upper case. 

Pascal lOSPaslib will not position the cursor past column 80 when 

Chapter 10 GOTOXY is usect even though the Lisa screen width is 88. 

Pascal Close files between RESETS because multiple RESETS on the 

Chapter 10 same file variable result in lORESULT > if there is no 
intervening CLOSE. 

Pascal Avoid using exec files with programs that RESET ITnPUT because 

Chapter 10 RESETting the INPUT file to KEYBOARD while execuUng an 
exec file produces a Bus Error. 
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Pascal If you WRITE or WRITELN a PACKED ARRAY OF CHAR, the 

Chapter 10 compiler reports error number 123 ~ error in type of standard 
procedure — unless the lower index is defined as 1. To avoid 
this error, assign the packed array to a string or WRITE the 
individual elements separately. 

Pascal OCXXMAXIhn) generates a range-check error during compllatioa 

Chapter 11 

Pascal The COPY function will accept a negative number for 

Chapter 11 COUNT, but the length of the definiUon string will be set to 

zera Thus, avoid algorithms that would attempt to copy with a 

negative number. 

Pascal Do not use an asterisk in the name of an include file if the $1 

Chapter 12 construct is enclosed in a (*-.*) style of compiler comment 
Instead use the {4 style of comment 

Pascal The predefined identifiers listed in the following three-page 

/appendix A table are built into the Pascal compiler for each machine, as 
indicated. If you declare or define these names in your 
program, no compiler error will result, but you will lose the 
capacity of the corresponding built-la or predefined, entity. 
The list does not include identifiers in special library units, such 
as those for graphics. 
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IrtenUfler 


Type 


Usa 


Afiple /// 


Apple ][ 


ABS 


Generic function 


Yes 


Yes 


Yes 


BLOCKREAD 


Integer function 


Yes 


Yes 


Yes 


BLOCKWRITE 


Integer function 


Yes 


Yes 


Yes 


BOO-EAN 


Type 


Yes 


Yes 


Yes 


BYlbSTREAM 


Type 


No 


Yes 


No 


CHAR 


Type 


Yes 


Yes 


Yes 


CHR 


Character function 


Yes 


Yes 


Yes 


CLOSE 


Procedure 


Yes 


Yes 


Yes 


CONCAT 


String function 


Yes 


Yes 


Yes 


COPY 


String function 


Yes 


Yes 


Yes 


DELETE 


Procedure 


Yes 


Yes 


Yes 


EOF 


Boolean function 


Yes 


Yes 


Yes 


EOLN 


Boolean function 


Yes 


Yes 


Yes 


EXIT 


Procedure 


Different 


Yes 


Yes 


EXP 


Real function 


Yes 


Yes 


Yes 


FALSE 


Constant 


Yes 


Yes 


Yes 


FILLCHAR 


Procedure 


Different 


Yes 


Yes 


RFT 


Procedure 


Yes 


Yes 


Yes 


GOTOXY 


Procedure 


Yes 


Yes 


Yes 


HALT 


Procedure 


Yes 


Yes 


Yes 


HEAPRESULT 


Integer function 


Yes 


No 


No 


IDSEARCH 


Procedure 


No 


Yes 


Yes 


INPUT 


File 


Yes 


Yes 


Yes 


INSERT 


Procedure 


Yes 


Yes 


Yes 


INTEGER 


Type 


Yes 


Yes 


Yes 


INTERACTIVE 


Type 


Yes 


Yes 


Yes 
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TdRnUfier 


Type 


Usa 


Apple /// 


Apple] 


lORESULT 


Integer aiiction 


Yes 


Yes 


Yes 


KEYBOARD 


File 


Device 


Yes 


Yes 


KEYPRESS 


Boolean function 


In library 


Yes 


Yes 


LENGTH 


Integer function 


Yes 


Yes 


Yes 


LN 


Real function 


Yes 


Yes 


Yes 


LOG 


Real function 


No 


Yes 


Yes 


LONGINT 


Type 


Yes 


No 


No 


MARK 


Procedure 


Different 


Yes 


Yes 


MAXIb4T 


Constant 


Yes 


Yes 


Yes 


MEMAVAIL 


Integer function 


Different 


Yes 


Yes 


MOVELEFT 


Procedure 


Different 


Yes 


Yes 


MOVERIGHT 


Procedure 


Different 


Yes 


Yes 


NEW 


Procedure 


Different 


Yes 


Yes 


OBJECT 


Type function 


In Clascal 


No 


No 


ODD 


Boolean function 


Yes 


Yes 


Yes 


ORD 


Integer function 


Yes 


Yes 


Yes 


0RD4 


Integer function 


Yes 


No 


No 


OUTPUT 


File 


Yes 


Yes 


Yes 


PAGE 


Procedure 


Yes 


Yes 


Yes 


POINIbR 


Pointer function 


Yes 


No 


NO 


POS 


Integer function 


Yes 


Yes 


Yes 


PRhU 


Integer function 


Yes 


Yes 


Yes 


PUT 


Procedure 


Yes 


Yes 


Yes 


PWROFTEN 


Real function 


Yes 


Yes 


Yes 


READ 


Procedure 


Yes 


Yes 


Yes 


READLN 


Procedure 


Yes 


Yes 


Yes 


REAL 


Type 


Yes 


Yes 


Yes 


RELEASE 


Procedure 


Diffeiera 


Yes 


Yes 


RESET 


Procedure 


Different 


Yes 


Yes 


REWRITE 


Procedure 


Yes 


Yes 


Yes 
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Identifier 


Type 


Usa 


Apple /// 


/We][ 


RCXJND 


Integer function 


Yes 


Yes 


Yes 


SCAN 


Integer function 


No 


Yes 


Yes 


SCAT^Q 


Integer function 


Yes 


NO 


NO 


SCANNE 


Integer function 


Yes 


NO 


NO 


SEEK 


Procedure 


Yes 


Yes 


Yes 


SIZEOF 


Integer function 


Yes 


Yes 


Yes 


SQR 


Generic function 


Yes 


Yes 


Yes 


SORT 


Real function 


Yes 


Yes 


Yes 


SIR 


String function 


No 


Yes 


Yes 


STRING 


Type function 


Length req 


1 Yes 


Yes 


SUCC 


Integer function 


Yes 


Yes 


Yes 


TEXT 


Type function 


Different 


Yes 


Yes 


TREESEARCH 


Integer function 


No 


Yes 


Yes 


TRUE 


Constant 


Yes 


Yes 


Yes 


TRUNC 


Integer function 


Yes 


Yes 


Yes 


UNITBUSY 


Boolean function 


NO 


Yes 


Yes 


UNITCLEAR 


Procedure 


No 


Yes 


Yes 


UNITREAD 


Procedure 


No 


Yes 


Yes 


UNITSTATUS 


Procedure 


No 


Yes 


NO 


UNITWAIT 


Procedure 


No 


Yes 


Yes 


UNITWRITE 


Procedure 


No 


Yes 


Yes 


WORDSTREAM 


Type 


NO 


Yes 


No 


WRITE 


Procedure 


Yes 


Yes 


Yes 


WRITELN 


Procedure 


Yes 


Yes 


Yes 
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Manuel 
Chapter 



Release Note 



Operating If a Pascal program contains Operating System user-interface 
System procedure calls^ then the USES clause of the program must 

ci^ter 1 specify the SYSCALL unit^ contained in the syscalLobJ file^ as in 
this example: 

Program MYF>ROG; 

USES (*»$U SYSCALL-Oej *) SYSCALL; 

Operating When a Device Control call specifies parity checking and when 
System bytes are being received from one of the serial ports^ the serial 

Oiapter 2 port driver does not reset the parity bit The application using 
the serial port must reset the parity bit 

Operating In the example of the use of event-wait channels. Process B, 
System the asslgpments to the receiver boolean are TRUE and then 

Ch^ter 5 FALSE. They should be FALSE and then TRUE. 

Operating Sysglobal Is the area of memory used to store data needed by 
System the Operating System. 

Appendix D 
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